- 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
3.9 KiB
| name | description |
|---|---|
| release | 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 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
Never bump the version on your own. Finished work is committed and pushed with its
bullets under ## [Unreleased], and you say it is ready to ship. A release happens only
when Frederic explicitly asks for one ("release", "ship it"), and then it includes
everything under ## [Unreleased]. Docs, skills, CI, issue templates, tests and
refactors are just pushed and never need a release.
At most one release per hour
Players get an update banner and a "What's new" window for every release, so ship at most one release an hour. Before bumping, check when the last one went out:
gh api repos/fjaeckel/seriesoftubes/releases/latest --jq '.tag_name+" "+.published_at'
- Less than 60 minutes ago: even when asked, say so and suggest waiting until the hour is up; release only if Frederic still wants it now.
- 60 minutes or more: release everything under
## [Unreleased]together, as one version. - Live game broken for players (it won't start, saves are lost, a phone can't get past a screen): tell Frederic right away and propose a hotfix release; still wait for his go.
Pick the version
- Several changes batched together: use the biggest one (any feature → minor).
- Patch (
x.y.Z): fixes, small tweaks, wording, icons. - Minor (
x.Y.0): new features or content.
Steps
- Make sure
mainis green:npm testandnode scripts/i18n-check.js("0 missing, 0 unused, 0 broken"). - 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. - Bump the version in both files:
package.json→"version"package-lock.json→ top-level"version"andpackages[""].version
npm testonce more. Then compare performance with the previous release and mention anything notable to Frederic:npm run perf -- --base-ref v<last>.- Commit on
mainas Frederic, with no attribution trailers: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 - Watch the workflows until both finish:
gh run list --repo fjaeckel/seriesoftubes --limit 4 gh run watch <id> --repo fjaeckel/seriesoftubes - Confirm it is live:
https://seriesoftub.es/version.jsonshows the new version.
Release notes rules
- The first sentence of each bullet is all the in-app "What's new" shows (at most five bullets; longer notes get a link to the full GitHub release). Make that sentence stand on its own: "Tier 1 networks can lay their own subsea cable (#22)." Detail goes after it.
- 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.