A version bump on main ran the whole suite twice: once in CI for the push, once more in auto-release. Auto-release now starts when CI finishes on main and releases only if that run was green, tagging the exact commit CI tested. Started by hand, it still tests first, since there is no CI result to go by.
109 lines
5.8 KiB
Markdown
109 lines
5.8 KiB
Markdown
---
|
|
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. CI tests the push
|
|
as usual; when it passes, `auto-release.yml` (which runs after every CI on `main`) sees
|
|
the new version, tags `v<version>` on the commit CI tested, 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.
|
|
|
|
## Weekly puzzles are not releases
|
|
|
|
`weekly-puzzle.yml` publishes a new puzzle every Sunday morning without a release: it commits the JSON under
|
|
`site/puzzles/weekly/` to `main` and redeploys the live tag through `release.yml` (`weekly=true`). Never bump the
|
|
version for a weekly puzzle. To publish or fix one by hand: `node scripts/weekly-puzzle.js --key 2026-W45 --force`,
|
|
`node scripts/weekly-puzzle.js --check`, commit to `main`, then run the "Weekly puzzle" workflow (or
|
|
`gh workflow run release.yml --ref <live tag> -f tag=<live tag> -f weekly=true`). A release includes every weekly
|
|
file on `main` when it builds.
|
|
|
|
The weekly scenario (`site/scenarios/weekly/`, `scripts/weekly-scenario.js`) ships in the same run and the same way:
|
|
`--key`, `--force` and `--check` work alike. Its `--check` replays each week not over yet with the reference plan in
|
|
the file; a new par is just written, a week the reference no longer wins is regenerated with `rev` + 1.
|
|
|
|
**Prices change, weeks follow.** `--check` re-solves every week not over yet with the game it runs; a week whose
|
|
budget no longer verifies is regenerated deterministically (the same puzzle with a new budget if that works, else a
|
|
fresh one for the same key) with `rev` + 1, which resets players' stars for that week only. Past weeks are left alone
|
|
unless the game rejects them. `release.yml` runs it before the tests on every deploy and fails only if a week cannot be
|
|
regenerated. A change to prices, cables or cities fails `npm test` until you run `node scripts/weekly-puzzle.js --check`
|
|
and commit the regenerated files with it (and `node scripts/weekly-scenario.js --check` for the scenarios).
|
|
|
|
## 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:
|
|
|
|
```bash
|
|
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
|
|
|
|
1. Don't run the test suite, the game or benchmarks before a release: CI tests the
|
|
version bump (a red CI releases nothing), and the Performance workflow benchmarks it. Just
|
|
check that the latest CI run on `main` is green (`gh run list --repo fjaeckel/seriesoftubes --limit 4`).
|
|
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. (Nothing to run here: the workflow tests the release before it tags it.)
|
|
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 all three finish (CI, then Auto-release, then Release to GitHub Pages):
|
|
```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
|
|
|
|
- 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.
|