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
|
|
@ -7,7 +7,7 @@ description: Add or change player-facing text in Series of Tubes and keep every
|
|||
|
||||
The English text is the translation key. Every string a player can see must go
|
||||
through the translation helpers and have an entry in every dictionary in `site/i18n/`
|
||||
(currently `it.js`, Italian).
|
||||
(Italian `it.js`, Portuguese `pt.js`, French `fr.js`). The code is in `src/`.
|
||||
|
||||
## In the code
|
||||
|
||||
|
|
@ -23,21 +23,25 @@ through the translation helpers and have an entry in every dictionary in `site/i
|
|||
|
||||
## In the dictionary
|
||||
|
||||
`site/i18n/it.js` is one object, `"English": "Italiano",` per line, ending with `};`.
|
||||
Append new entries before the closing `};`. A small script avoids quoting mistakes:
|
||||
`site/i18n/<lang>.js` is one object, `"English":"Translation",` per line, **sorted by the English
|
||||
text**. Sorted files mean two pull requests that add strings touch different lines instead of both
|
||||
appending at the end. Don't edit the lines by hand; use the script, which quotes correctly, keeps the
|
||||
order and works on every dictionary at once:
|
||||
|
||||
```python
|
||||
import json
|
||||
it = {"New English text": "Nuovo testo italiano"}
|
||||
q = 'site/i18n/it.js'; t = open(q).read().rstrip()
|
||||
assert t.endswith('};')
|
||||
t = t[:-2] + ''.join(json.dumps(k, ensure_ascii=False) + ':' + json.dumps(v, ensure_ascii=False) + ',\n'
|
||||
for k, v in it.items() if json.dumps(k, ensure_ascii=False) + ':' not in t) + '};\n'
|
||||
open(q, 'w').write(t)
|
||||
```bash
|
||||
cat > /tmp/strings.json <<'JSON'
|
||||
{
|
||||
"it": { "New English text": "Nuovo testo italiano", "Text that was removed": null },
|
||||
"pt": { "New English text": "Novo texto em português" },
|
||||
"fr": { "New English text": "Nouveau texte en français" }
|
||||
}
|
||||
JSON
|
||||
node scripts/i18n-add.js /tmp/strings.json # a string adds or replaces, null removes
|
||||
node scripts/i18n-add.js --rename "Old English" "New English" # English text changed: move the key everywhere
|
||||
```
|
||||
|
||||
When you **change** English text, rename the key in every dictionary too; when you
|
||||
remove text, delete its entry.
|
||||
If a dictionary got out of order anyway (a hand edit, a merge), `npm run i18n:fix` sorts it again;
|
||||
`npm run i18n:check` fails until it is sorted.
|
||||
|
||||
## Italian style
|
||||
|
||||
|
|
|
|||
67
.claude/skills/edit-the-game/SKILL.md
Normal file
67
.claude/skills/edit-the-game/SKILL.md
Normal file
|
|
@ -0,0 +1,67 @@
|
|||
---
|
||||
name: edit-the-game
|
||||
description: Find, change and add game code in Series of Tubes, which lives in many small files under src/ that the build joins into one page. Use for any feature, fix or refactor in the game itself (anything in src/).
|
||||
---
|
||||
|
||||
# Editing the game
|
||||
|
||||
The game's source is `src/`. The build (`scripts/lib/page.js`) pastes the files together, in path order,
|
||||
into one `index.html` with one inline `<style>` and one inline `<script>`. That is exactly what players
|
||||
load, so splitting code across files costs nothing at runtime. Why it works this way:
|
||||
[docs/adr/0002-one-page-assembled-at-build.md](../../../docs/adr/0002-one-page-assembled-at-build.md).
|
||||
|
||||
```
|
||||
src/index.html the shell: <head>, static markup, `<!-- @include styles -->`, `<!-- @include game -->`
|
||||
src/styles/NN-*.css CSS, in order (phones last)
|
||||
src/game/NN-area/NN-*.js the game script, in order (see the map in docs/ARCHITECTURE.md)
|
||||
site/ static files copied as they are (dictionaries, icons, service worker)
|
||||
```
|
||||
|
||||
## Find the code
|
||||
|
||||
Search by name, not by line: `grep -rn "function compute(" src/game`. Folder names say what lives
|
||||
there: `10-catalog` prices and gear, `20-world` cities and cables, `30-networks` other ASes,
|
||||
`70-rules` peering and market rules, `80-simulation` routing and the save gate, `85-incidents`,
|
||||
`88-days` the daily tick, `90-actions` every player action, `93-ui` HUD and panels, `94-dashboard`,
|
||||
`95-modals`, `96-map` the canvas. `docs/ARCHITECTURE.md` has the full table.
|
||||
|
||||
## Run it
|
||||
|
||||
```bash
|
||||
npm run dev # http://localhost:8080, assembled on every request, reloads on save
|
||||
npm test # all suites (assembles src/ in memory; no build needed)
|
||||
npm test -- tests/peering.test.js # one suite
|
||||
```
|
||||
|
||||
A browser error points at a line of the assembled page; the dev server prints the `src/` file and line
|
||||
next to it. `npm run page -- -o /tmp/page.html` writes the assembled page if you want to look at it.
|
||||
|
||||
## Where new code goes
|
||||
|
||||
- **A new feature or system:** its own file in the folder of its topic, e.g.
|
||||
`src/game/70-rules/85-route-servers.js`. Pick a number between its neighbours; gaps are there for this.
|
||||
Small files that own one topic are what keep pull requests from conflicting.
|
||||
- **Order matters at the top level.** Files run in path order. Top-level `const`/`let` values and
|
||||
top-level statements may only use top-level values from earlier files. Functions are fine anywhere:
|
||||
everything is one script, so function declarations are hoisted and are all defined by the time
|
||||
anything runs after boot. When in doubt, put constants in an earlier file and logic in functions.
|
||||
- **Actions:** add `name:(args)=>{…},` to the matching `src/game/90-actions/*.js`. Only
|
||||
`10-interface.js` declares `const ACT={`; the others are `Object.assign(ACT,{ … });`. A new area can get
|
||||
a new `NN-area.js` file of that second form.
|
||||
- **Panels and modals:** `93-ui/` (HUD, side panels), `94-dashboard/` (NOC dashboard, bank), `95-modals/`.
|
||||
- **Styles:** the matching `src/styles/*.css`; phone rules go in `60-phone.css`.
|
||||
- **Data tables** (cities, cables, networks): one entry per line, and keep id-keyed objects such as
|
||||
`CITY_LL` sorted by id, so two people adding cities touch different lines.
|
||||
- **Static markup** goes in `src/index.html`; it is short and rarely changes.
|
||||
- **Files that ship as they are** (icons, dictionaries, `sw.js`, `robots.txt`) live in `site/`.
|
||||
`site/index.html` must not exist; the build refuses it.
|
||||
|
||||
Every partial ends with a newline and must not contain `</script>` or `</style>` at the start of a line.
|
||||
File names are `NN-lower-case.js` / `.css`; `tests/build.test.js` checks both.
|
||||
|
||||
## Still the same rules
|
||||
|
||||
Everything in CLAUDE.md applies unchanged: translate every string (`add-strings`), sanitize saves,
|
||||
phones first, a test with every change (`write-tests`), performance shown against `main`
|
||||
(`performance`), hosting on GitHub Pages only (`github-pages`), a CHANGELOG bullet for players.
|
||||
The CHANGELOG is the one file every change touches; a conflict there is expected: keep both bullets.
|
||||
52
.claude/skills/github-pages/SKILL.md
Normal file
52
.claude/skills/github-pages/SKILL.md
Normal file
|
|
@ -0,0 +1,52 @@
|
|||
---
|
||||
name: github-pages
|
||||
description: Series of Tubes is hosted on GitHub Pages and nowhere else, non-negotiably. Use before any change to hosting, deploys, the build output, caching, the service worker, new runtime requests or anything that would need a server, and whenever someone suggests another host.
|
||||
---
|
||||
|
||||
# GitHub Pages, always
|
||||
|
||||
Series of Tubes is served by GitHub Pages at https://seriesoftub.es and **only** there. This is settled
|
||||
([docs/adr/0001-github-pages-only.md](../../../docs/adr/0001-github-pages-only.md)) and not up for
|
||||
discussion: do not propose, prepare or "keep the door open" for another host, a CDN in front, a
|
||||
backend or server-side rendering, even when asked to evaluate options. If a feature seems to need
|
||||
one, redesign the feature.
|
||||
|
||||
## What that means for a change
|
||||
|
||||
- **The output is static files.** `npm run build` writes `_site/`: the assembled page, `site/`'s files,
|
||||
`version.json`. No server code, no runtime secrets: everything there is public.
|
||||
- **No HTTP headers, redirects or rewrites.** Pages ignores `_headers`, `_redirects`, `.htaccess`,
|
||||
`vercel.json`, `netlify.toml`. Need a policy? Use a `<meta>` tag. Need a different URL? Add a
|
||||
static file there.
|
||||
- **Caching is Pages' (short, the same for every file) plus the service worker's.** Offline play and
|
||||
updates are `site/sw.js`'s job; its cache name carries the version. When you add a file the game
|
||||
needs offline, add it to `CORE` there.
|
||||
- **Same origin.** The page, dictionaries, icons and data come from seriesoftub.es. Do not add CDN
|
||||
libraries or third-party APIs the game needs to work; the web fonts and the analytics counter are
|
||||
the only exceptions and the game runs without them.
|
||||
- **More files are fine, from the same origin.** Pages serves many small files well over HTTP/2.
|
||||
Still: the game page itself stays one assembled `index.html` (see
|
||||
[ADR 0002](../../../docs/adr/0002-one-page-assembled-at-build.md)), and anything the first frame
|
||||
needs must not add a round trip.
|
||||
- **Limits:** about 1 GB for the whole site, 100 MB per file.
|
||||
- **Paths:** the site lives at the domain root (`site/CNAME`), so `/` paths are fine; unknown paths get
|
||||
`404.html`.
|
||||
|
||||
## How it deploys
|
||||
|
||||
Only releases deploy. Bumping `version` in `package.json` on `main` runs `auto-release.yml`, which tags,
|
||||
publishes the GitHub release and starts `release.yml`: test, `REQUIRE_NOTES=1 npm run build`,
|
||||
`actions/upload-pages-artifact` with `./_site`, `actions/deploy-pages`. That job is the only one with
|
||||
`pages: write`. Pushes to `main` and pull requests build but never deploy. The `release` skill has the
|
||||
steps.
|
||||
|
||||
## Before you hand back a change that touches the build, deploy or loading
|
||||
|
||||
```bash
|
||||
npm run build && npm run serve # the production build, served as static files
|
||||
npm test -- tests/pages.test.js # static-only, all references resolve, Pages-only deploy
|
||||
```
|
||||
|
||||
`tests/pages.test.js` fails on host configuration files, files over the limits, local references
|
||||
that do not exist in `_site/`, scripts loaded from other origins, and any workflow that deploys
|
||||
anywhere else. Do not weaken it to make a change pass; change the change.
|
||||
|
|
@ -5,7 +5,7 @@ description: Measure and demonstrate the performance of every Series of Tubes ch
|
|||
|
||||
# Performance is always demonstrated
|
||||
|
||||
Every change to the game (anything in `site/`) shows its performance on a very large network,
|
||||
Every change to the game (anything in `src/` or `site/`) shows its performance on a very large network,
|
||||
compared with `main`, before it is merged or released. A speed claim without numbers does not
|
||||
count, and neither does "it feels fine on my small game". Most players who complain about lag
|
||||
have huge late-game networks, and most of them are on phones.
|
||||
|
|
@ -13,11 +13,14 @@ have huge late-game networks, and most of them are on phones.
|
|||
## Measure
|
||||
|
||||
```bash
|
||||
git show origin/main:site/index.html > /tmp/base.html
|
||||
npm run perf -- --base /tmp/base.html # headless only, a few minutes
|
||||
npm run perf -- --base /tmp/base.html --browser # plus real Chromium, desktop and phone (what CI runs)
|
||||
npm run perf -- --base-ref origin/main # headless only, a few minutes
|
||||
npm run perf -- --base-ref origin/main --browser # plus real Chromium, desktop and phone (what CI runs)
|
||||
```
|
||||
|
||||
`--base-ref` assembles that commit's page with its own scripts (`node scripts/lib/page.js --ref REF`;
|
||||
for commits from before the split it reads their `site/index.html`). `--base FILE` takes a built page
|
||||
instead. The head is always this checkout's `src/`, assembled the way the build does it.
|
||||
|
||||
`scripts/perf-bench.js` loads `tests/fixtures/big-network.json` (about 100 POPs, 150 links,
|
||||
950 PNIs, 830 cache boxes, 110 IX ports, 170 customers) into the base and into this checkout and
|
||||
times them in alternating turns, 15 runs each. It prints one table per environment:
|
||||
|
|
@ -57,7 +60,7 @@ Without `--base` it just times this checkout. `--runs N`, `--md FILE`, `--json F
|
|||
save and a file from the in-game menu's Export save work:
|
||||
|
||||
```bash
|
||||
npm run perf -- --save ~/Downloads/series-of-tubes-save.json --base /tmp/base.html
|
||||
npm run perf -- --save ~/Downloads/series-of-tubes-save.json --base-ref origin/main
|
||||
```
|
||||
|
||||
Routing speed-ups must also keep the two equivalence tests green: `tests/speed.test.js` (the fast
|
||||
|
|
@ -70,10 +73,10 @@ incidents and failures).
|
|||
- **Every pull request**: the Performance workflow runs the same comparison and posts the table as a
|
||||
comment on the PR (updated on every push). Read it before merging. Locally, paste the table into
|
||||
the PR description or the commit summary you report.
|
||||
- **Everything you hand back to Frederic** that touched `site/`: include the table, or at least the
|
||||
- **Everything you hand back to Frederic** that touched `src/` or `site/`: include the table, or at least the
|
||||
rows that moved, in your summary. Say plainly when something got slower.
|
||||
- **Before a release**: compare the release against the previous tag
|
||||
(`git show v<last>:site/index.html > /tmp/base.html`) and mention notable changes.
|
||||
(`npm run perf -- --base-ref v<last>`) and mention notable changes.
|
||||
|
||||
## Read the table
|
||||
|
||||
|
|
|
|||
|
|
@ -7,8 +7,10 @@ description: Cut and ship a Series of Tubes release (patch or minor) from main v
|
|||
|
||||
Bumping `version` in `package.json` on `main` is the release button. The
|
||||
`auto-release.yml` workflow tests, tags `v<version>`, publishes a GitHub release with
|
||||
that version's CHANGELOG section as notes, and dispatches `release.yml`, which deploys
|
||||
to GitHub Pages (https://seriesoftub.es).
|
||||
that version's CHANGELOG section as notes, and dispatches `release.yml`, which builds
|
||||
`_site/` (`npm run build`: the page assembled from `src/` plus `site/`) and deploys it
|
||||
to GitHub Pages (https://seriesoftub.es). GitHub Pages is the only host, ever: see the
|
||||
`github-pages` skill.
|
||||
|
||||
## Only release when Frederic says so
|
||||
|
||||
|
|
@ -53,7 +55,7 @@ gh api repos/fjaeckel/seriesoftubes/releases/latest --jq '.tag_name+" "+.publish
|
|||
- `package-lock.json` → top-level `"version"` and `packages[""].version`
|
||||
4. `npm test` once more.
|
||||
Then compare performance with the previous release and mention anything notable to Frederic:
|
||||
`git show v<last>:site/index.html > /tmp/base.html && npm run perf -- --base /tmp/base.html`.
|
||||
`npm run perf -- --base-ref v<last>`.
|
||||
5. Commit on `main` as Frederic, with no attribution trailers:
|
||||
```bash
|
||||
git -c user.name="Frederic Jung" -c user.email="frederic@jc-ix.net" commit \
|
||||
|
|
|
|||
|
|
@ -5,8 +5,8 @@ description: Write deterministic jsdom tests for Series of Tubes features and fi
|
|||
|
||||
# Writing tests
|
||||
|
||||
Tests use `node:test` and `tests/harness.js`, which loads `site/index.html` in jsdom
|
||||
with the animation loop off, a seeded `Math.random` and a recording fake canvas.
|
||||
Tests use `node:test` and `tests/harness.js`, which assembles the game page from `src/`
|
||||
(once per test file) and loads it in jsdom with the animation loop off, a seeded `Math.random` and a recording fake canvas.
|
||||
Code runs inside the page through `ev()`.
|
||||
|
||||
## Pattern
|
||||
|
|
@ -29,8 +29,11 @@ test('what the player should see happen', () => {
|
|||
|
||||
Pick the suite by topic: `game` (core loop), `build`, `persist` (save/import/migrate),
|
||||
`services` (customers), `peering`, `issues` (GitHub issue regressions, name them
|
||||
`#NN …`), `regions`, `modes` (scenarios, sandbox, weekly), `i18n`. A new file must be
|
||||
added to the `test` script in `package.json`.
|
||||
`#NN …`), `regions`, `modes` (scenarios, sandbox, weekly), `i18n`, `pages` (hosting).
|
||||
For a new feature, prefer a new file named after it (`tests/route-servers.test.js`): every
|
||||
`tests/*.test.js` runs on its own (`scripts/test.js`), and a file of your own never conflicts
|
||||
with someone else's tests. Appending to the big suites (`issues`, `regions`) is where
|
||||
pull requests collide. Run one file with `npm test -- tests/route-servers.test.js`.
|
||||
|
||||
## Rules
|
||||
|
||||
|
|
@ -40,7 +43,7 @@ added to the `test` script in `package.json`.
|
|||
```js
|
||||
ev("eval('('+fireFailure.toString().replace('const e=pick(opts);',\"const e='crash';\")+')')()");
|
||||
```
|
||||
Check the current source for the exact `pick` line first; it may differ.
|
||||
Check the current source for the exact `pick` line first (`grep -rn "function fireFailure" src/game`); it may differ.
|
||||
- **Drive the game through `ACT`** like a player would, then `compute()` or `dayTick()`.
|
||||
- **Saves:** for persistence changes, round-trip `JSON.stringify(S)` through
|
||||
`parseSave()`/`migrate()`, and test that an *old* save without the new field still loads.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue