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
66
CLAUDE.md
Normal file
66
CLAUDE.md
Normal file
|
|
@ -0,0 +1,66 @@
|
|||
# Series of Tubes: notes for Claude
|
||||
|
||||
A free cartoon browser game about how the internet works, live at
|
||||
https://seriesoftub.es. The whole game is one static page: `site/index.html`
|
||||
(HTML, CSS and JS in one file, no framework, no build step for development).
|
||||
|
||||
Read these before larger changes:
|
||||
|
||||
- `docs/ARCHITECTURE.md`: how the code is laid out and how a day of simulation runs.
|
||||
- `.claude/skills/`: step-by-step procedures (release, translations, tests).
|
||||
|
||||
## Commands
|
||||
|
||||
```bash
|
||||
npm ci # once: installs jsdom for the tests
|
||||
npm test # node:test + jsdom, all suites, must stay green
|
||||
node scripts/i18n-check.js # must report "0 missing, 0 unused, 0 broken"
|
||||
npm run build # builds _site/ (stamps version, bakes release notes)
|
||||
npm run serve # build and serve locally
|
||||
```
|
||||
|
||||
To play during development, open `site/index.html` directly or run `npm run serve`.
|
||||
|
||||
## Hard rules
|
||||
|
||||
- **Git:** work on `main`, no branches. Commits are authored and committed as
|
||||
`Frederic Jung <frederic@jc-ix.net>`. Never add `Co-Authored-By`, `Claude-Session`
|
||||
or any other attribution trailers.
|
||||
- **Releases** happen by bumping `version` in `package.json` on `main` (see the
|
||||
`release` skill). Small fixes or tweaks get a patch release (`x.y.Z`); new features a
|
||||
minor release.
|
||||
- **Names are puns.** No real company names for networks, vendors, cables, banks,
|
||||
data centers or exchanges (Cogentle, Goggle, NetChill, Junipurr, Arrrhipster…).
|
||||
Real conference names (NANOG, RIPE, DENOG) are fine. Avoid lazy "-ish" names: find
|
||||
a real pun, or keep the plain word.
|
||||
- **Easter eggs stay secret.** Never mention hidden jokes or easter eggs (for example
|
||||
whatever `elephant()` does) in commit messages, release notes or the CHANGELOG.
|
||||
- **Every player-facing string is translated.** Wrap it in `tr()`, `trn()` or `N_()`
|
||||
and add the Italian to `site/i18n/it.js` in the same change (see `add-strings`).
|
||||
- **Phones first.** About 70% of players are on phones. Every new panel, button and
|
||||
modal must work at 360 px wide, in portrait and landscape, using the phone tab bar
|
||||
and bottom sheets. Check `isPhone()` layouts, not just desktop.
|
||||
- **Saves are sacred.** Old saves must keep loading. Any new state field gets a default
|
||||
in `newGame()` and a check/repair in `sanitize()`; renamed fields are migrated there.
|
||||
- **Tests come with features.** Add or extend a test in `tests/` for every feature or
|
||||
fix. Tests are seeded, so they must not depend on luck.
|
||||
- **CHANGELOG style:** plain English, written for players, one bullet per change,
|
||||
issue numbers in parentheses like `(#37)`. No internal names, no jokes explained.
|
||||
|
||||
## Style of the code
|
||||
|
||||
- Dense, single-file JavaScript. Match the surrounding style: short helper names,
|
||||
arrow functions, template-literal HTML, no new dependencies.
|
||||
- UI is rebuilt from state: change `S`, then call `after()` (recompute, check goals,
|
||||
re-render, save). Buttons are `btn(label, actName, args, cls, disabled)`, which
|
||||
dispatch to `ACT[actName](args)` through `data-act`/`data-args`.
|
||||
- Never trust saved or imported state: anything read from `S` that came from a save
|
||||
must already have been validated in `sanitize()`.
|
||||
- Keep comments short and about *why*.
|
||||
|
||||
## Tone
|
||||
|
||||
Friendly, nerdy and accurate underneath the jokes. Mechanics should follow how
|
||||
networks really work (95th-percentile billing, peering policies, LAGs, DWDM reach,
|
||||
route leaks, RPKI) and then exaggerate for fun. When unsure how something works in
|
||||
real life, look it up before modelling it.
|
||||
Loading…
Add table
Add a link
Reference in a new issue