Add MIT license, contributing guide, CLAUDE.md, architecture notes and repo skills
This commit is contained in:
parent
06576357c9
commit
443202876a
10 changed files with 457 additions and 1 deletions
53
.claude/skills/add-strings/SKILL.md
Normal file
53
.claude/skills/add-strings/SKILL.md
Normal 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
|
||||
```
|
||||
55
.claude/skills/release/SKILL.md
Normal file
55
.claude/skills/release/SKILL.md
Normal 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.
|
||||
49
.claude/skills/write-tests/SKILL.md
Normal file
49
.claude/skills/write-tests/SKILL.md
Normal 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue