[joshunrau]

Implements the release and support policy decided in #1870 and supersedes #1822. A merge to main stops overwriting the published latest and 2.5.2 images, deployers get a published policy saying which versions receive which fixes, and a superseded major can ship fixes from a release/<major> branch.

Changes

• A push to main publishes only edge and sha-<7> images. <version>, <major> and latest move only when the root version has no v* tag yet, which means after a version bump. latest and 2.5.2 stop tracking main.
• A release pushes <version> and <major> (for example 2), and a release from main also moves latest and publishes npm. <major>.<minor> is never published.
• A superseded major releases from release/<major> on dispatch, and only once a higher major is tagged. That run publishes images and a GitHub release not marked latest, and skips npm with a notice. CI now runs on pull requests to release/**.
• One Release run at a time across every branch. A run waits for the one in flight instead of cancelling it. GitHub keeps only one waiting run, so a third run cancels the waiting one; if that was a release from main, the next push releases the version anyway.
• The GitHub release tag goes on the commit the run built, not on the default branch's head.
• .env.template defaults RELEASE_CHANNEL to 2 instead of latest. A .env generated from now on tracks the current major.
• engines.node is ^24.22.1 || >=26.12.1, Gabriel's October 2026 Node security fix from ci: release from release branches and keep latest on tagged releases #1822, unchanged.
• scripts/increment-version.ts enforces the policy:
  • It allows only a major bump once a breaking commit is in range.
  • On a superseded major it allows only a patch bump and refuses a breaking or feat commit.
  • A major bump rewrites RELEASE_CHANNEL and the end-of-support table.
• New user docs page, Versioning and Support (docs/en/5-reference/5.10-versioning.md), covering:
  • what a version promises;
  • which versions get which fixes, for 18 months after a major is superseded;
  • which image tag to run;
  • installing from a release tag and upgrading by git checkout.
• Other docs follow the new page. SECURITY.md links to it and points reporters at private vulnerability reporting. The deployment guide clones a release tag instead of main.

Decisions

• latest and npm move only with a release from main. A branch release cannot move them, because planRelease refuses a release/<major> dispatch until a higher major is tagged. With that guarantee, ci: release from release branches and keep latest on tagged releases #1822's dist-tag reconciliation (publish-npm.cjs) is no longer needed.
• A superseded major takes patch bumps only. The policy supports only its last minor, so a feat commit in range fails the bump instead of producing a new minor on the branch.
• The support table is dated by month, using the month of the bump, not the exact release date. The release ships when the bump's PR merges, so a day-precise date would be wrong whenever the merge comes later.
• The release decision reads git tags only, never GHCR or npm. This is kept from ci: release from release branches and keep latest on tagged releases #1822: a deleted image or package cannot wedge the next release.

Risks

• No 2 image tag exists until the first release after this merges. Until then, a .env generated from main points at a tag GHCR does not have. Existing deployments keep RELEASE_CHANNEL=latest, which now moves only on a release. The fix is to release 2.6.0 soon after merging.
• Most of the new workflow behaviour runs for the first time on a real release:
  • The first release after merging is the first run of the new tags, make_latest and target_commitish.
  • A release/<major> dispatch will first run after 3.0.0 ships.
  • Until then, planRelease's unit tests are the only check of that path.

Filed: #1896, #1900

Notes

I ran scripts/increment-version.ts by hand on throwaway state and reverted every run:

• A major bump rewrote RELEASE_CHANNEL=3 and the table: it added 3 | 2026-11 and marked 2 superseded in 2026-11, supported until 2028-05.
• With the row for 2 removed from the table, a major bump failed and wrote no file.
• With a temporary local v3.0.0 tag, --bump minor and a feat commit were both refused.
• Without that tag, --bump minor after a feat! commit was refused.

The docs site builds with the new page at /en/docs/reference/versioning/.

Adversarial review

Reviewed at commit f67a438. pnpm check: green.

Findings

1. scripts/increment-version.ts:487 — a major bump writes .env.template and the support table only after every version file and both changelogs, so a missing RELEASE_CHANNEL line or table row leaves the tree half-bumped and a rerun bumps from the wrong version — compute and check both edits before the first write.
2. scripts/increment-version.ts:212 — a superseded major offers and accepts a minor bump, letting a feature release onto a branch that takes fixes only — allow patch only, and refuse a feat commit in range as the breaking case is refused.
3. scripts/increment-version.ts:191 — "superseded major" and version parsing are defined here and again in .github/scripts/release.cjs, two artifacts that must agree — export them from release.cjs and import them.
4. scripts/increment-version.ts:411 — the fallback rule ?? 'it is not allowed here' can never run — make every restricted case carry its rule and drop the fallback.
5. vitest.config.ts:24 — the narrowed coverage exclude {apps,packages,runtime}/*/scripts/** matches no file the coverage include admits — delete it.
6. .github/scripts/__tests__/release.test.ts:101 — the entrypoint tests stub readFileSync and getExecOutput without checking their arguments, so reading the wrong file or listing the wrong tags would still pass — assert both calls.
7. .github/scripts/release.cjs:5 — the ReleasePlan typedef says what each field is in doc comments — drop them and let release-channels.md's output table be the one explanation.

Fixed

• 1. Both edits, including the prettier pass, are computed before any version field is written, and only written after the lockstep check.
• 2. A superseded major allows only patch; a feat or breaking commit in range fails the run.
• 3. release.cjs exports parseVersion and isSupersededMajor, planRelease uses the latter, and increment-version.ts imports both.
• 4. allowBumps takes the requested bump and throws with the rule of the branch that restricted it; the fallback is gone.
• 5. The exclude entry is deleted.
• 6. The tests assert readFileSync('package.json', 'utf-8') and getExecOutput('git', ['tag', '--list', 'v*']).
• 7. The descriptions are dropped, with a pointer to release-channels.md.

Attestation

I, Claude Opus 5.5, attest that the review block above reports the adversarial review as it ran on the commit named, with every finding it returned.

🤖 Generated with Claude Code