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:
Frederic Jung 2026-10-27 10:15:12 +01:00
parent 052fdd713f
commit 05ff4ea7ad
No known key found for this signature in database
15 changed files with 530 additions and 101 deletions

View file

@ -18,19 +18,49 @@ Not sure yet whether something is a bug or an idea worth an issue? Ask in the
## Development
The game is one static page, `site/index.html`, with no framework and no build step
while developing.
The game is one static page with no framework, hosted on GitHub Pages. Its source is split into
small files under `src/` (styles in `src/styles/`, the game script in `src/game/`), which the build
joins, in path order, into a single `index.html`. Static files such as the translations live in `site/`.
```bash
npm ci # installs jsdom for the tests
npm run serve # builds and serves the game locally
npm run dev # http://localhost:8080, reloads when you save a file
npm test # all tests must pass
node scripts/i18n-check.js # translations must be complete
node scripts/i18n-check.js # translations must be complete and sorted
npm run serve # the production build, as GitHub Pages will serve it
```
Opening `site/index.html` directly in a browser also works.
Where things are, and how a day of the simulation runs: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
A tour of the code is in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
### Keeping pull requests apart
Many people work on the game at once. A few habits keep your pull request from colliding with theirs:
- Put a new feature in its own file in the folder of its topic (for example
`src/game/70-rules/85-route-servers.js`), and its tests in their own `tests/<feature>.test.js`.
New files in `src/` and `tests/` are picked up automatically; nothing needs registering.
- Add actions to the matching file in `src/game/90-actions/`, not wherever there is room.
- Lists (cities, cables, networks) take one entry per line; keep id-keyed tables sorted.
- Add translations with `node scripts/i18n-add.js` rather than by hand: it keeps the dictionaries
sorted, so your new strings don't land on the same lines as everyone else's.
- The `CHANGELOG.md` bullet is the one place everybody writes. If it conflicts, keep both bullets.
### Your branch still edits `site/index.html`?
Until version 1.33 the whole game was one file, `site/index.html`. If your branch was started before
the split, merge `main` and let a script move your changes into `src/`:
```bash
git fetch origin
git merge origin/main # stops: site/index.html was deleted on main
node scripts/legacy/port-branch.js # moves your edits into the matching src/ files
git status # fix any conflict it lists, then
npm test && git commit
```
It splits your version of the page and the one you started from the same way `src/` was made, merges
each piece into `src/`, and applies your dictionary changes entry by entry. It only reports conflicts
where your change and `main` touched the same lines.
## Pull requests
@ -42,11 +72,14 @@ A tour of the code is in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
must not depend on luck.
- Add a bullet for players under `## [Unreleased]` in `CHANGELOG.md`, in plain English.
Releases are cut by the maintainer.
- Show the performance of changes to `site/` on a big network. The Performance check posts a table
- Show the performance of changes to `src/` on a big network. The Performance check posts a table
comparing your PR with `main` as a comment; to run it yourself:
`git show origin/main:site/index.html > /tmp/base.html && npm run perf -- --base /tmp/base.html`
`npm run perf -- --base-ref origin/main`
(add `--browser` to also time it in Chromium as a desktop and a phone, like CI does).
Anything marked slower needs an explanation.
- The game is hosted on GitHub Pages, and that will not change. Changes must work as plain static
files: no server code, no other host, no redirects or custom headers (see
[docs/adr/0001-github-pages-only.md](docs/adr/0001-github-pages-only.md)).
- Old saves must keep loading. New state needs a default for new games and a check in
`sanitize()`.
- Check your change on a phone-sized screen (about 360 px wide). Most players are on
@ -64,8 +97,8 @@ A tour of the code is in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
## Translations
Every player-facing string goes through `tr()`, `trn()` or `N_()`. Dictionaries live
in `site/i18n/` (English text → translation). To add a language, copy `it.js`, translate
the values, register the language in the language list in `site/index.html`, and run
in `site/i18n/` (English text → translation, one entry per line, sorted). To add a language, copy
`it.js`, translate the values, register the language in the language list in `src/index.html`, and run
`node scripts/i18n-check.js <lang>` until it reports nothing missing, unused or broken. The CI job "translations" runs the same check on every pull request, shows each language's coverage in the run summary, and also fails if a new language is not added to the language list or to the offline cache in `site/sw.js`.
Language pull requests must be reviewed by a human who speaks the language, and