feat: [release] harden /release — preflight script, fail-closed tags, publish gates
Merged
AN
4mo ago+1103+1103+0123456789012345678901234567890123456789-79-79-01234567890123456789
PINEAPPLE
Summary
Hardens the /release process based on a full-trace retro of the last three releases (v0.8.10, v0.9.1, v0.9.2). Each release hit at least one live failure that process should have caught:
- v0.9.1 nearly published the wrong artifact: a stale local
v0.9.1tag madegit tagsilently no-op and the push sent a tag pointing at a 2641-commit-divergent commit. Caught by vigilance, not process. - v0.9.2 hit a fork-inherited tag collision, smoke-tested a stale globally-installed
0.7.3binary while releasing0.9.2, and burned 7 serial marker-guard fix rounds. publish-npmwas never gated on thetestjob — npm could publish with typecheck/tests red.
Changes:
script/release-preflight.ts(+34 unit tests) — deterministic, fail-closed preflight gate: clean tree; HEAD == freshorigin/main(stagepre) or ancestor (stagetag); local+remote tag-collision check that never auto-deletes; version sanity vs npm (SemVer, monotonic, unpublished); prerelease-line ancestry (the missing check that turned v0.9.1 into a 17-hour merge side-quest); openrelease-blockerPRs;PREV_TAGdry-run (replicatesrelease.ymlselection); marker guard with full output in one pass..github/workflows/release.yml—publish-npmnowneeds: [test, build, sanity-verdaccio]; newValidate release tagstep (format, tag-SHA == checked-out SHA,CHANGELOG.mdentry for stable releases) runs BEFORE any publish; pre-publish smoke test asserts the exact tag version instead of just "binary starts"..claude/commands/release.md— preflight as the Step 2 gate; stop-never-improvise on structural failures; three-step verified commit/tag +git push --atomic origin HEAD:main v{V}; fail-closed tag rules; exit-status integrity rule (no trailing status echoes on gates); smoke-test the dist binary by path; deferred findings require durable issue links; P0-candidates verified or explicitly downgraded with rationale; every step visible (✅/⏭️/❌) in the final summary; persona reviewers deliver viaSendMessagebefore idling.docs/RELEASING.md— targeted staging instead ofgit add -A; atomic push with pre-push tag verification; honest wording: AUR publishing is disabled, Docker publish is best-effort.
Test Plan
-
bun test script/release-preflight.test.ts— 34/34 pass (semver precedence incl. stable > prerelease, the exact v0.9.1PREV_TAGbug, malformed-tag rejection) - E2E:
bun script/release-preflight.ts --version 99.0.0 --stage precorrectly FAILs (branch ahead oforigin/main, exit 1);--stage tagPASSes 9/9 - Negative E2E:
--version 0.9.2correctly FAILs on tag collision (shows local+remote SHA) and already-published npm version -
bun test test/branding/ test/install/(the CItestjob's exact scope, which assertsrelease.ymlcontents) — 442 pass / 0 fail - Marker guard
--strictclean;release.ymlYAML validated
Checklist
- Tests added/updated
- Documentation updated
- CHANGELOG updated (release-process change only; no user-facing behavior — will land in the next release's changelog if desired)
Closes #1031
🤖 Generated with Claude Code
Summary by cubic
Tightens the release flow with a deterministic preflight gate, fail‑closed tag rules, strict SemVer, and stronger CI publish gates. Adds authoritative tag validation, exact‑version smoke checks, and blocks beta downgrades.
-
New Features
script/release-preflight.ts: clean worktree; HEAD == freshorigin/main(pre) ororigin/mainis ancestor (tag); fail‑closed local/remote tag collision check; strict SemVer (no leading zeros, no empty prerelease ids); npm reachability/unpublished enforced (fail‑closed); prerelease ancestry checked against HEAD; beta targets must be > currentbetadist‑tag;release-blockerPRs gate;PREV_TAGdry‑run; marker guard with full output; unit tests added./release-beta: runs preflight with--allow-prerelease; fail‑closed local/remote tag collision and “tag-at-HEAD” checks before pushing.
-
Bug Fixes
- CI:
publish-npmnow needstest;release.ymlvalidates tag format and SHA viagit ls-remote origin(incl.^{}peel) and requires a stable changelog entry before publish; pre‑publish smoke asserts the exact tag version;PREV_TAGpicks the highest merged stable strictly lower than the target; preflight tests run in CI. - Marker guard: fails if
analyze.tsdegrades to pattern‑only due to a missing upstream remote. Docs (RELEASING.md,.claude/commands/release(-beta).md): preflight is the gate; verify tags before push; pushHEAD:mainatomically; targeted staging (no-A); run stage‑tagpreflight after the release commit; smoke‑test the built binary with an injected version; Docker is best‑effort and AUR is disabled.
- CI:
Summary by CodeRabbit
-
New Features
- Added deterministic release preflight validation for versioning, tags, changelog entries, repository state, and publishing readiness.
- Strengthened release workflows with tag collision checks, atomic pushes, commit verification, and expanded CI validation.
- Improved generated release notes by selecting the correct previous stable release.
-
Documentation
- Updated release guides with the new preflight process, verification steps, and release requirements.
-
Tests
- Added comprehensive preflight validation tests and integrated them into CI.