Cut a release candidate
This is the maintainer’s checklist. The full flow, what each step of the
script does and how to recover from a failed cut are in
RELEASING.md.
scripts/cut-release.sh is the single source of the steps; never repeat them
by hand.
Know the base. Every release is cut from
mainunless.github/patch-branches.txtmaps a patch’s minor torelease-X.Y.scripts/release-base.sh X.Y.Zprints it, and the script picks the base the same way, never from your checkout (ADR 0102).Check the base is green. No release is cut from a red
mainorrelease-X.Y. The cut refuses while a check the base requires is red on its tip or on the merge commit, and so does the Release workflow on the tagged commit; there is no override for a required check. An openci-redissue (“CI is red on main”) is fixed first:scripts/release-ci-gate.sh "$(git rev-parse origin/main)" mainA red check the base does not require stops the cut at the merge commit too, unless
--allow-red="<reason>"records why it does not matter; the reason goes into the tag annotation (RELEASING.md).Close the gaps. The cut refuses a patch while the first list is not empty, and any candidate while the second is not:
scripts/release-gap.sh X.Y.Z --fetch # mapped minors: main commits the patch would miss scripts/docs-gap.sh X.Y.Z --fetch # user-facing changes without docsA change that will never ship in the minor goes in
.github/release-skip.txton the release branch, with its reason.Run the end-to-end gates on the candidate’s commit.
make rc-smokeruns the gates and the k3d suites. The performance gates workflow (.github/workflows/e2e-gates.yaml) and the soak smoke run nightly onmainand on rc tags, and the daemonless deploy workflow (.github/workflows/e2e-daemonless-deploy.yaml:dexaflow deployofexamples/taskflow_salesfrom thedexaflow-cliimage with no container daemon, then a run on k3d) on rc tags only, so start all three withworkflow_dispatchon the candidate’s commit (on its base branch) before the cut. On a machine where another project owns port 5432, runDEXAFLOW_DEV_DB_PORT=55432 make rc-smoke: the dev Postgres, the migrations, the integration tests, the k3d suites and the UI smoke all use that port, and the battery never resets a database it did not start.make soakalready runs on its own Postgres on port 55433 (SOAK_PG_PORT).Record every review of AGENTS.md section 1 in the tracking issue of the
vX.Y.Zmilestone: one line each, with who did it, the result and a link to the evidence, including the reviews that do not apply and why. The script does not check these lines; whoever runs it does.Preview, then cut:
scripts/cut-release.sh vX.Y.Z-rc.N --dry-run scripts/cut-release.sh vX.Y.Z-rc.NThe script prepares the release PR, waits for it to go green, merges it, and asks you to type the tag back before it pushes. It refuses while the Actions queue is busy: wait for it to drain and resume, or pass
--force-queuewhen the release cannot wait.Freeze pull request pushes from the go-ahead until the release run is green, so release jobs do not wait behind PR runs.
If the cut stops after the prepare PR merged, fix the cause and resume:
scripts/cut-release.sh vX.Y.Z-rc.N --resume --dry-run, then without--dry-run.
Before promoting the candidate to GA, run the GA rows of
test/release/perf-reliability-checklist.md and, on a real cluster,
test/release/rc-cluster-validation.md.