Pre Release Check

Pre-release check

This is the last thing that runs before a release is cut. Nothing downstream catches what you miss here.

Releases are cut by release-please: a bot PR titled chore(main): release <version> sits open against main, and the release happens the moment it merges — tagging, publishing images, and cutting a GitHub release. There is no undo.

Three mechanics shape the whole check:

• The changelog is built only from Conventional Commit subjects on main.
• main squash-merges with the PR title as the commit subject. A PR titled without a feat/fix/chore prefix lands a commit that contributes nothing to the changelog and nothing to the version bump — a feature ships silently inside a patch release.
• main is protected against force-pushes, so a subject that landed wrong cannot be rewritten. It can only be corrected by a follow-up commit.

You end on a verdict: ship or hold. A hedge is a hold. Everything below feeds that one call, so run every step — a skipped step is an unknown, and an unknown holds.

Step 1 — Go green

Confirm the ground first: on main, synced with origin/main, working tree clean.

git fetch --tags && git fetch origin main
git status --short && git log --oneline origin/main..HEAD

Lint, typecheck and tests are not re-run here. CI runs them on every push to main, so the tip has already been through them — but "CI runs on main" is only a guarantee if you look at the result. Read it:

git rev-parse origin/main
gh run list --branch main --workflow ci.yml --limit 1 \
  --json headSha,status,conclusion,url --jq '.[0]'

The run's headSha must equal origin/main and its conclusion must be success. Three ways that goes wrong, all holds:

• The newest run is for an older commit. The tip is unverified — most likely it arrived by a push that bypassed the pull request, which is how a security fix lands off a private advisory. Wait for its run, or trigger one.
• No run at all, or one still in progress. Wait for it. An absent result is not a passing one.
• A failing run. Stop here.

Do not accept the release PR's own green check as evidence. CI skips lint, typecheck and tests on any branch starting release-please--, and the gate job passes on skipped jobs — so the release PR is green whatever state the code is in. The run that means something is the one on main.

Then run what CI does not cover, from the repo root:

pnpm build

Then pnpm format followed by git status --short. format writes, so a dirty tree afterwards means formatting has drifted on main and needs its own commit. Neither the build nor formatting drift is checked anywhere upstream of here.

Report the CI run and each local check as pass or fail, with the failing output. Green is a CI success on this exact commit plus every local check passing on an unmodified tree. Anything red is a hold — say so and stop; do not carry a failure forward into the later steps hoping it looks smaller in a summary.

Step 2 — Reconcile the release

Establish the range: previous release tag to the tip of main.

git tag --sort=-v:refname | head -1        # previous release
gh release view <prev-tag>                 # what it told self-hosters
gh pr list --state open --search "chore(main): release" --json number,title,body
git log <prev-tag>..origin/main --oneline
git diff <prev-tag>..origin/main --stat

Read the previous release's notes first. A changelog lists what changed; the notes are where a breaking change gets its commentary — the migration step, the deprecation naming the release that removes it, the caveat a self-hoster acted on. That commentary is the state this upgrade starts from, so the pending range can complete it, contradict it, or strand someone who followed it.

Then read the release PR body (its changelog), then the range itself — open every file the stat flags as substantial. Never reconcile from commit subjects alone; the subject is the thing under suspicion.

Every commit in the range must be accounted for: it either appears in the changelog, or you name it and say what it actually changed. Hunt specifically for a subject that isn't feat/fix/chore — that commit is invisible to release-please.

Report:

• Commits in the range but absent from the changelog, with what each actually changed.
• Whether the proposed bump matches the largest change in the range — a feat in the range and a patch bump on the PR is a hold.
• Anything breaking: a removed or renamed env var, a changed default, an API or schema shift a self-hoster upgrades into. Breaking work in a non-major release is a hold.
• The next major's milestone (v<N>.0.0, e.g. gh issue list --milestone v4.0.0 --state all). It holds one issue per planned breaking change, each deprecated during the current major. If this release is a major, list every issue that is still open. Each one is a break this major was meant to carry, and whether to hold the release or move the issue to the following major's milestone is the user's call. If it isn't a major, an issue from the milestone that closed in the range is breaking work shipping early, which is a hold. A deprecation this range introduces with no removal issue on the milestone will be forgotten, so name it.
• Commentary in the previous notes that this range settles, contradicts, or strands — a deprecation this range removes, a migration step it invalidates, a "lands next release" it either delivers or silently skips.
• User-facing changes the changelog technically lists but doesn't convey.

The remedy for a mismatched bump is the user's call, not yours. Surface it and stop.

Step 3 — Sweep what CI can't see

The gate Step 1 confirmed is a floor. These four hold the release and none of them go red:

• Focused or disabled tests. grep -rn "\.only(\|\.skip(\|todo(" --include="*.test.ts" --include="*.test.tsx" apps packages — a .only left in the range silently disables the rest of its file, so CI went green over tests that never ran. Any hit introduced in this range is a hold until it's removed or justified.
• Docs that ship with the code. CLAUDE.md maps changed paths to the docs page that must change with them — .example.env, packages/schemas limits, apps/backend/src/plugins/**, and visible frontend labels. Apply that table to the range's paths: if a mapped path changed and apps/docs/content didn't, the release ships a docs lie. docs-contract.test.ts already passed in CI and cannot see UI labels; for those, ask the user to run /docs-audit — it is user-invoked and you cannot start it yourself.
• The plugin SDK version. If the range touches packages/plugin-sdk, its package.json version must already be bumped by hand. publish-sdk.yml fires on release publish and publishes only when that version isn't on npm — an unbumped SDK means the release goes out with SDK changes that never reach consumers.
• Migrations. If the range adds a migration, confirm it's a real .sql file that drizzle-kit migrate will run in production, not a dev-only push that exists nowhere but a developer's database. Then check the journal: every new entry's when in apps/backend/drizzle/meta/_journal.json must be later than every entry before it. Drizzle applies only entries newer than the database's newest recorded migration, so a migration generated on a branch before its lower-numbered neighbour merged is skipped by every database that already ran that neighbour — and fresh installs, including dev, apply it fine, so nothing local notices. That is how 3.7.0 shipped without the skill columns 3.6.0 upgraders needed. An out-of-order entry is a hold; migration-journal.test.ts now pins this, but check the range by hand as well.