Docs and guard rails: GitHub Pages only, where code goes, updated skills
- docs/adr/0001: GitHub Pages is the only host, not open for renegotiation - docs/adr/0002: source in many files, shipped as one page assembled at build - tests/pages.test.js: builds stay static files Pages can serve, all local references resolve, only release.yml deploys and only via the Pages actions - tests/build.test.js: partial naming and layout rules - new skills: github-pages, edit-the-game; add-strings, performance, release and write-tests updated for src/, sorted dictionaries and --base-ref - CLAUDE.md, ARCHITECTURE.md, CONTRIBUTING.md (incl. porting older branches), README.md and the PR template describe the new layout
This commit is contained in:
parent
052fdd713f
commit
05ff4ea7ad
15 changed files with 530 additions and 101 deletions
54
docs/adr/0001-github-pages-only.md
Normal file
54
docs/adr/0001-github-pages-only.md
Normal file
|
|
@ -0,0 +1,54 @@
|
|||
# ADR 0001: Series of Tubes is hosted on GitHub Pages, and only there
|
||||
|
||||
- Status: accepted, not open for renegotiation
|
||||
- Date: 2026-10-27
|
||||
- Decided by: Frederic Jung
|
||||
|
||||
## Decision
|
||||
|
||||
The game is served by **GitHub Pages**, from the custom domain in `site/CNAME`
|
||||
(https://seriesoftub.es). That is the only hosting. There is no second host, no fallback host and no
|
||||
plan to move.
|
||||
|
||||
Every change has to keep working there. A change that only works with a server, a different host,
|
||||
a CDN in front, edge functions, rewrites or custom response headers is the wrong design for this
|
||||
project, however good it is otherwise. Change the design, not the host.
|
||||
|
||||
## What GitHub Pages gives us, and what it does not
|
||||
|
||||
| We can rely on | We cannot have |
|
||||
| --- | --- |
|
||||
| Static files over HTTPS from one origin, with gzip | Any server code: no API routes, no SSR, no PHP, no edge or serverless functions |
|
||||
| The deploy in `release.yml` (`actions/upload-pages-artifact` + `actions/deploy-pages`) | Custom HTTP headers (`Cache-Control`, CSP, COOP/COEP): use `<meta>` tags or do without |
|
||||
| `404.html` for unknown paths | Redirect or rewrite rules (`_redirects`, `.htaccess`, `vercel.json`, `netlify.toml`) |
|
||||
| `CNAME` for the domain | Per-file caching rules: Pages sets its own short cache lifetime for everything |
|
||||
| A size limit of about 1 GB for the site and 100 MB per file | Secrets at runtime: everything in `_site/` is public |
|
||||
|
||||
Anything that needs data at runtime fetches it from the same origin as a static file
|
||||
(`version.json`), from the player's own browser (`localStorage`), or not at all.
|
||||
|
||||
## Consequences
|
||||
|
||||
- **The build is the place for work.** Anything clever (assembling the page from `src/`, stamping the
|
||||
version, baking release notes) happens in `scripts/build.js`, at build time, in GitHub Actions.
|
||||
The build may get slower; what it produces must stay plain static files. See
|
||||
[ADR 0002](0002-one-page-assembled-at-build.md).
|
||||
- **Same origin for everything the game loads.** The page, the dictionaries, icons and the service
|
||||
worker all come from seriesoftub.es. The only cross-origin requests are the web fonts and the
|
||||
privacy-friendly analytics counter (its script and its endpoint), and the game works without both.
|
||||
Don't add more: no CDN-hosted libraries, no third-party APIs the game depends on.
|
||||
- **The service worker is the cache policy.** Since Pages decides HTTP caching, `site/sw.js` decides
|
||||
what is cached for offline play, versioned by the release.
|
||||
- **Deploys only come from releases.** `release.yml` is the only workflow with `pages: write`. Pushes to
|
||||
`main` never deploy.
|
||||
- **Tests guard it.** `tests/pages.test.js` checks that a build is plain static files that GitHub
|
||||
Pages can serve as they are: no server or host configuration files, every local reference resolving
|
||||
inside `_site/`, nothing over the size limits, `CNAME` and `404.html` in place, and the deploy going
|
||||
through the official Pages actions.
|
||||
|
||||
## Proposals that are out of scope
|
||||
|
||||
Moving to Netlify, Vercel, Cloudflare Pages or a VPS; putting a CDN or proxy in front; adding a
|
||||
backend for accounts, leaderboards or cloud saves; server-side rendering. Features in that direction
|
||||
must be built from static files and the browser (for example, an exported save file instead of a cloud
|
||||
save), or not at all.
|
||||
68
docs/adr/0002-one-page-assembled-at-build.md
Normal file
68
docs/adr/0002-one-page-assembled-at-build.md
Normal file
|
|
@ -0,0 +1,68 @@
|
|||
# ADR 0002: Source in many files, shipped as one page assembled at build
|
||||
|
||||
- Status: accepted
|
||||
- Date: 2026-10-27
|
||||
|
||||
## Context
|
||||
|
||||
Until 1.33 the whole game was `site/index.html`: about 900 KB and 5,100 lines of HTML, CSS and JavaScript
|
||||
in one file, edited by many contributors at once. Nearly every pull request touched that file, so
|
||||
pull requests conflicted with each other all the time, reviews meant scrolling a 900 KB file, and
|
||||
nobody could tell from a diff's file list what a change was about.
|
||||
|
||||
What had to stay: hosting on GitHub Pages ([ADR 0001](0001-github-pages-only.md)), load time and in-game
|
||||
speed (most players are on phones), saves, the tests that reach into the page's globals (`S`, `R`,
|
||||
`ACT`, `compute()`), and no new runtime dependencies.
|
||||
|
||||
## Decision
|
||||
|
||||
- The page's source lives in `src/`: a shell (`src/index.html`) with `<!-- @include DIR -->` lines,
|
||||
the styles in `src/styles/*.css` and the game script in `src/game/**/*.js`.
|
||||
- `scripts/lib/page.js` assembles them by **plain concatenation in path order** into the same single,
|
||||
self-contained `index.html` as before: one inline `<style>`, one inline classic `<script>`.
|
||||
The numeric prefixes (`10-`, `20-`…) set that order; gaps leave room to add files in between.
|
||||
- `scripts/build.js` builds `_site/` from that page plus the static files in `site/`.
|
||||
- Nothing else changes at runtime. When the split landed, the assembled page was byte-for-byte the old
|
||||
`site/index.html`.
|
||||
|
||||
## Why concatenation, and not ES modules or a bundler
|
||||
|
||||
- **Zero runtime cost.** One HTML request, as before. ES modules would mean many requests (or a bundler),
|
||||
module graph evaluation and a new loading order; at best they break even.
|
||||
- **The code is one script on purpose.** The partials share top-level names (`S`, `R`, `UI`, `CITY`,
|
||||
`tr`…) and function declarations are hoisted across the whole script. Concatenated, every partial
|
||||
sees exactly what it saw before, with no `import`/`export` lists to keep in sync (another source of
|
||||
conflicts) and no circular-import pitfalls.
|
||||
- **Tests keep working.** jsdom loads the assembled page, and tests still call into its globals and
|
||||
patch functions by their source text.
|
||||
- **No dependencies.** The assembler is about a hundred lines of Node with nothing to install, so it
|
||||
runs anywhere `npm test` does, including GitHub Actions.
|
||||
- **It is reversible.** If a bundler is ever worth it, the partials are already the modules it needs.
|
||||
|
||||
## Rules that come with it
|
||||
|
||||
- **Order matters for top-level code.** `const`/`let` and statements at the top level of a partial run
|
||||
in path order, so a partial can only use top-level *values* from partials that come before it (or
|
||||
inside functions that run later, after boot). Functions can be called from anywhere once the page
|
||||
has loaded.
|
||||
- **A partial is a complete set of statements.** Each file ends with a newline and never closes the
|
||||
`<script>`/`<style>` it is pasted into; the assembler refuses files that break this.
|
||||
- **Put new code where its topic is.** A new feature gets its own partial in the right folder (for
|
||||
example `src/game/70-rules/85-my-feature.js`), its actions go in the matching
|
||||
`src/game/90-actions/*.js`, its panel in `src/game/93-ui/` or `src/game/94-dashboard/`. Small files
|
||||
that own one topic are what keep pull requests apart.
|
||||
- **Keep lists one entry per line.** Tables people add to (cities, cables, networks, dictionaries) have
|
||||
one entry per line, and the id-keyed ones are sorted, so additions land in different places.
|
||||
- **The CHANGELOG is the one shared file every change touches**, on purpose: one bullet per change under
|
||||
`## [Unreleased]`. A conflict there is expected and easy: keep both bullets.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Development needs one command: `npm run dev` serves the page assembled on every request and reloads
|
||||
the browser on save. Opening a file straight from disk no longer runs the game.
|
||||
- Error line numbers in the browser refer to the assembled page; the dev server prints the matching
|
||||
`src/` file and line in the console.
|
||||
- Branches started before the split are carried over with `scripts/legacy/port-branch.js`
|
||||
(see CONTRIBUTING.md).
|
||||
- The performance workflow builds the base's page from git with that commit's own assembler
|
||||
(`node scripts/lib/page.js --ref REF`), so base and head are always compared as players get them.
|
||||
Loading…
Add table
Add a link
Reference in a new issue