Skip to content

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 ​

  1. Add your notes under ## Unreleased in CHANGELOG.md, as before.

  2. Say the release level in the PR description, on a line of its own:

    text
    Release: minor
    LevelWhen
    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):

  1. finds the PR merged as that commit and reads its level,
  2. on top of main, bumps package.json and website/version.json and moves Unreleased under ## x.y.z, led by a line such as Minor release: <PR title> (#N). (Unreleased empty means the PR title is the whole note),
  3. commits that as Release x.y.z (#N) through GitHub's API, so the commit is signed,
  4. tags it vX.Y.Z and 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.