msd-core/docs/adr/660-release-from-next-head.md

ADR 660: Release from the head of next; immutable release tags; @next dist-tag as the RC surface [Proposed]

• Status: Proposed
• Date: 2026-06-03

Context

The release pipeline (.github/workflows/release.yml) is a three-mode workflow_dispatch (create / rc / finalize) built around a persistent, long-lived release/<version> branch:

• create cuts release/<version> from next and commits a version bump.
• rc checks out that same branch (ref: release/<version>), bumps to -rc.N, tags v<version>-rc.N, and publishes to the @next npm dist-tag.
• finalize checks out that same branch, bumps to the final version, tags v<version>, publishes to @latest, opens a PR back to main, and auto-backmerge.yml later merges main → next.

This has a structural defect. No job ever brings post-create work from next into the release branch — there is no git merge/rebase/cherry-pick from next anywhere in release.yml. So the moment RC testing surfaces a bug:

1. The fix is (correctly) committed to next — our trunk.
2. The release/<version> branch does not receive it.
3. finalize therefore ships the rc-cut tree, missing every RC fix.

To compensate, we have been hand-moving the v<version> tag forward to the head of next each cycle. This is the "dance every release." It is two documented antipatterns stacked:

• Freezing a release branch you never backport into. Trunk-based development requires fixes to flow trunk → release branch (fix on trunk, cherry-pick down), never "fix on trunk and leave the release branch behind" (trunkbaseddevelopment.com/branch-for-release). GitFlow's own author now steers continuous-delivery projects away from this model (nvie.com).
• A movable release tag. Git's manual ("On Re-tagging") and SemVer both forbid it — "Once a versioned package has been released, the contents of that version MUST NOT be modified" (semver.org). Moving a published tag breaks our SSH signatures, already-fetched clones, caches, and the GitHub Release; GitHub shipped Immutable Releases (GA 2025) specifically to stop this.

We have meaningful existing investment we want to keep: the homegrown changeset/CHANGELOG fragment system (scripts/changeset/*.cjs, changeset-required.yml), the curated release-notes formatter (scripts/release-notes/format-github-release-notes.cjs), the inter-stage smoke-test gates, provenance publishing, and the main(@latest) / next(integration)

• auto-backmerge topology — which is already the correct "main holds releases, next is integration" shape.

Decision

Stop persisting/freezing the release branch. Always release from the current head of next, create each release git tag exactly once, and treat the @next npm dist-tag — not a git branch or a movable tag — as the RC surface. Concretely:

1. The release point is always next's head at invocation time. rc and finalize derive their tree from the current origin/next HEAD rather than reusing a stale release/<version> branch. Implementation: recreate (or hard-reset) an ephemeral release/<version> branch from origin/next HEAD at the start of each rc/finalize run. The final version-bump commit lands on this short-lived branch and reaches main via the release PR; the branch is a scratch staging area, not a frozen snapshot — so it always contains every RC fix.

2. next carries a -dev prerelease version (the dev stream). Between releases, next's package.json no longer rests at the last-released number — it carries X.Y.Z-dev.N for the anticipated next version, so the trunk self-identifies as unreleased. Default floor after releasing A.B.C is the next patch, A.B.(C+1)-dev.0 (precedence-safe: greater than A.B.C, and it never overstates the eventual release, which finalize may set higher). @next dist-tag publishes carry this -dev snapshot identity; rc overrides it with the chosen -rc.N; finalize sets the final number. After finalize + the main→next backmerge, a post-release step bumps next to the new -dev floor.

3. Release tags are immutable, created once, by finalize only. No tag is ever pre-created as a placeholder or force-moved. finalize mints v<version> on the final commit and pushes it once. (This also removes the manual step that currently breaks finalize, whose tag-existence guard hard-errors on any pre-existing v<version> tag.) RC tags v<version>-rc.N remain — each N is unique and never moved, so they are already immutable and serve the GitHub prerelease.

4. RC = the @next dist-tag, full stop. Testers run npm i -g @opengsd/gsd-core@next. Because each rc run is cut from next HEAD, every rc.N already includes all prior fixes. No long-lived branch, no tag movement. finalize promotes the released version to @latest (@next remains the prerelease channel managed exclusively by the rc job; finalize does not repoint it).

5. Everything else stays: custom changesets + CHANGELOG render, release-notes formatter, smoke-test gates, provenance, main/next, auto-backmerge (main→next).

In short: the immutable v<version> tag that finalize creates — landing on main via the release→main PR — is the "historical marker for the release" we wanted. The intuition was right; only the movable placeholder mechanic was wrong.

Alternatives considered

• Adopt release-please. Auto-updating Release PR off next would also kill the freeze, and tags are immutable. Rejected for now: it generates CHANGELOG from conventional commits, displacing our custom changeset-fragment system; its prerelease→stable transition has known open bugs (googleapis/release-please #2515, #2447). Migration cost > the defect it fixes.
• Adopt @changesets/cli. Closest to our homegrown system and has a mature auto-updating Version PR. Rejected for now: would replace working in-house tooling, and its pre mode has real footguns (the pre.json-not-staged bug silently publishes stable under the rc dist-tag — changesets #1150).
• Adopt semantic-release. Lowest ceremony, native next→main channel promotion. Rejected: "auto-release on every conventional commit" removes the deliberate "decide to cut a release" gate we want, and again displaces our changeset/changelog system.
• Keep the persistent branch but cherry-pick RC fixes into it. The textbook trunk-based approach. Rejected as primary: for a single active version it is pure bookkeeping overhead, and "forgot to cherry-pick" is exactly the regression trap the literature warns about. Re-cutting from next HEAD gets the same result with zero manual cherry-picks.

Consequences

Positive

• The "dance" is gone: RC fixes are included by construction; no manual tag moves; no frozen branch to reconcile.
• Tags become trustworthy and signature-valid — one commit, one immutable tag, per release.
• We keep all existing investment (changesets, formatter, smoke gates, backmerge) — small, low-risk diff to release.yml, no new third-party release dependency.

Negative / costs

• release.yml changes required: rc/finalize must recreate/reset the release branch from origin/next at start; remove any reliance on a pre-existing tag.
• create becomes near-vestigial (its only job — seed the branch + bump — folds into rc/ finalize re-cutting from next). Decide whether to delete create or keep it as an optional "open the release branch early" convenience.
• One-version assumption is now explicit: this model does not support maintaining multiple live majors (LTS). If that need ever arises, revisit (long-lived release/x.y + cherry-pick is the escape hatch).

Rollout

• File this ADR first (maintainer decision): land the proposing issue + ADR PR before any release action, so the model is documented before it is first exercised.
• 1.3.0 (first manual run): ship it as the first manual application of this model — recreate release/1.3.0 from next HEAD (6bd7ceb2), delete the hand-moved v1.3.0 tag so finalize mints it fresh, then run finalize (dry-run first). This validates the model by hand before we codify it. Immediately after, bump next to its first -dev floor (1.3.1-dev.0).
• Codify (1.4.0+): update release.yml per the Decision (re-cut from next, -dev stream, post-release -dev bump); update docs/branching.md; delete or repurpose create.

Resolved by maintainer (2026-06-03)

• Approach: re-cut from next's head; keep the in-house tooling (no third-party release tool).
• next version: move to a -dev stream (Decision §2), not resting at last-released.
• Sequencing: file this ADR first, then ship 1.3.0 as the first manual run.

Open questions (remaining)

1. Delete the create action, or keep it as an optional early-branch convenience? (Recommend: delete; re-cut from next makes it redundant.)
2. Keep immutable v<version>-rc.N git tags, or rely on the @next dist-tag alone for RCs? (Recommend: keep the rc tags — harmless, immutable, and they anchor the GitHub prerelease.)
3. -dev floor increment: next-patch (A.B.(C+1)-dev.0, the precedence-safe default above) or next-minor (A.(B+1).0-dev.0)? (Recommend: next-patch floor.)

Amendment (2026-06-12, #1104): next tracks the last published release

Supersedes the §2 / "Resolved by maintainer" choice to rest next on a -dev stream.

The -dev floor (e.g. 1.3.1-dev.0) was never published to npm, yet it became the source-of-truth version on the default branch and leaked to the real world via source/dev installs that report package.json's version — a version no release ever bore. To eliminate phantom versions, next now rests at the last published release and is synced automatically by the release pipeline for every release type:

• finalize / hotfix (these push main): the existing main → next back-merge (.github/workflows/auto-backmerge.yml) sets next's version to main's released version, folded into the same back-merge PR.
• rc (publishes a pre-release to the release/<version> branch + @next; does not push main): the rc job in .github/workflows/release.yml opens and admin-merges a chore: sync next package version PR after a confirmed publish.

Both paths share scripts/sync-next-version.cjs, which sets package.json and stamps the runtime manifests (plugin.json, gemini-extension.json) via the version lifecycle hook, and refuses any non-release version string (fail-closed — a -dev/placeholder can never be written to next again). Open question 3 (the -dev floor increment) is therefore moot: there is no -dev floor.