Add MIT license, contributing guide, CLAUDE.md, architecture notes and repo skills

This commit is contained in:
Frederic Jung 2026-10-25 07:07:00 +01:00
parent 06576357c9
commit 443202876a
No known key found for this signature in database
10 changed files with 457 additions and 1 deletions

View file

@ -0,0 +1,53 @@
---
name: add-strings
description: Add or change player-facing text in Series of Tubes and keep every translation (site/i18n/*.js) complete.
---
# Adding or changing player-facing text
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).
## In the code
- `tr('Text with {name}', {name})`: translate now and fill placeholders.
- `trn('{n} router', '{n} routers', n, vars)`: plurals; both forms are keys.
- `N_('Text')`: marks a literal kept in a table for later `tr()` (e.g. labels stored in
constants). Call `tr(x)` where it's shown.
- Static HTML: add `data-i18n` to the element; `aria-label` and `title` attributes are
collected automatically.
- Text must be a string literal inside the call, or the checker can't see it.
- Keep HTML (`<b>`, `<br>`, `<small>`) and `{placeholders}` identical in translations.
- Don't build sentences by concatenating translated fragments; translate whole sentences.
## 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:
```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)
```
When you **change** English text, rename the key in every dictionary too; when you
remove text, delete its entry.
## Italian style
Natural, friendly Italian, informal "tu". Keep networking terms that Italian engineers
use in English (peering, transit, router, POP, PNI, LAG, dark fiber). Translate puns
into an Italian joke when one fits; otherwise keep the pun name and translate the rest.
## Check
```bash
node scripts/i18n-check.js # must say: 0 missing, 0 unused, 0 broken
npm test # includes tests/i18n.test.js
```

View file

@ -0,0 +1,55 @@
---
name: release
description: Cut and ship a Series of Tubes release (patch or minor) from main via the auto-release workflow.
---
# Releasing Series of Tubes
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).
## Pick the version
- Patch (`x.y.Z`): fixes, small tweaks, wording, icons.
- Minor (`x.Y.0`): new features or content.
## Steps
1. Make sure `main` is green: `npm test` and `node scripts/i18n-check.js`
("0 missing, 0 unused, 0 broken").
2. In `CHANGELOG.md`, move the bullets from `## [Unreleased]` into a new section
right below it: `## [x.y.z] — YYYY-MM-DD` (em dash, today's date). Keep an empty
`## [Unreleased]` heading above it. The build fails if the section has no bullets.
3. Bump the version in **both** files:
- `package.json` → `"version"`
- `package-lock.json` → top-level `"version"` and `packages[""].version`
4. `npm test` once more.
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 \
--author="Frederic Jung <frederic@jc-ix.net>" -m "Short summary (x.y.z)"
git push origin main
```
6. Watch the workflows until both finish:
```bash
gh run list --repo fjaeckel/seriesoftubes --limit 4
gh run watch <id> --repo fjaeckel/seriesoftubes
```
7. Confirm it is live: `https://seriesoftub.es/version.json` shows the new version.
## Release notes rules
- Written for players, in plain English. One bullet per change, issue numbers like `(#37)`.
- Never mention hidden easter eggs or explain jokes.
- No internal function names.
## If something fails
- "not newer than the latest release": the version was not bumped, or was bumped
backwards.
- "CHANGELOG.md has no notes under ## [x.y.z]": the heading doesn't match the version
exactly or has no bullets.
- Tests fail in the workflow but pass locally: look for unseeded randomness in a test.
- Fix forward with a new patch version; never move or delete an existing tag.

View file

@ -0,0 +1,49 @@
---
name: write-tests
description: Write deterministic jsdom tests for Series of Tubes features and fixes in tests/*.test.js.
---
# 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.
Code runs inside the page through `ev()`.
## Pattern
```js
const test = require('node:test');
const assert = require('node:assert/strict');
const { load } = require('./harness');
test('what the player should see happen', () => {
const { ev, errors } = load();
ev("ACT.start({});S.cash=1e8;for(const g of GOALS)S.done[g.id]=0;ACT.launchBB({city:'fra'})");
ev("ACT.buyTransit({city:'fra',net:'cog',tier:1});compute()");
assert.ok(ev("R.served") > 0);
assert.deepEqual(errors, []); // always: no page errors
});
```
## Where to put it
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`.
## Rules
- **Deterministic.** Never rely on luck. Use the default seed, `window.__reseed(n)`,
or set state directly (`S.day=…`, `S.ev.x=…`).
- **Force a specific random failure or event** by patching the picker:
```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.
- **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.
- **UI:** render with `renderAll()` and query `dom.window.document`; check phone
layouts by setting `window.innerWidth = 390` before rendering.
- Run `npm test`; the whole suite must pass, not just the new test.