Releases
Every PR merged to main is a release (#1547). Versions follow semver and live in package.json, website/version.json, CHANGELOG.md, git tags (vX.Y.Z) and GitHub Releases. The marketing site footer and the hub (chrome + Settings → About) show the number.
In each PR
Add your notes under
## UnreleasedinCHANGELOG.md, as before.Say the release level in the PR description, on a line of its own:
textRelease: minorLevel When patchFixes, copy, docs, dependency bumps minorNew features and behaviour changes that break nothing majorBreaking: data shape or migrations, auth or sessions, billing, public APIs or URLs, Terraform/infra, a removed feature These match the "breaking" list in the merge rule: a PR that needs Mark's go before merging is usually
major.
The Release level check fails until the description has exactly one level, and runs again when the description is edited. Dependabot PRs release as patch without a line. Hub registry PRs (only platform/sites.yaml, worker/wrangler.toml, worker/package.json, platform-admin/public/platform-manifest.json) are not releases, the same list Deploy on merge skips.
On merge
The Release on merge workflow (.github/workflows/release-on-merge.yml, scripts/release-on-merge.mjs):
- finds the PR merged as that commit and reads its level,
- on top of
main, bumpspackage.jsonandwebsite/version.jsonand moves Unreleased under## x.y.z, led by a line such asMinor release: <PR title> (#N).(Unreleased empty means the PR title is the whole note), - commits that as Release x.y.z (#N) through GitHub's API, so the commit is signed,
- tags it
vX.Y.Zand publishes the GitHub release from that CHANGELOG section.
Runs go one at a time in merge order, so two quick merges get two versions.
Deploys follow releases
The release commit is pushed with PLATFORM_GITHUB_TOKEN (the token the registry commits use), so its push runs CI and Deploy on merge like any push to main. Deploy on merge does nothing for the PR merge itself and posts no Deploy statuses on it (#1550); the release commit's run deploys every part that changed since its last successful deploy. So what goes live is always a released version, and the marketing footer and hub chrome show its number (the hub shows the release of its last hub change, since a version bump alone doesn't redeploy every hub).
If Release on merge fails for a merge, that merge doesn't deploy either until the release is re-run. Slack alerts on the failure.
package-lock.json keeps its old root version: changing it would redeploy every hub on every release, and npm ci doesn't compare it.
When a release run fails
Open the failed Release on merge run; the error says what's wrong (most often a PR merged without a Release: line). Fix it (edit the PR description if needed), then run Release on merge by hand with the PR number; its release commit then deploys. A re-run for a PR that already has its release commit only finishes the tag and the GitHub release, so it never bumps twice.
Don't tag or edit versions by hand: the next merge reads package.json on main as the current version.
History
Releases up to 3.8.0 were cut by hand from a batch of merged work. 4.0.0 (the PR that added this) carries everything merged between 3.8.0 and 10 November 2026.