The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
feat(release): candidate-branch beta builds and the release checklist (#11209)
Devin Foley71e9d6bb0b7a
diff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex 3e07b36372..931694db1b 100644--- a/.github/workflows/release.yml+++ b/.github/workflows/release.yml@@ -31,6 +31,10 @@ on:description: For nightly, the explicit canary version to promote (empty selects the newest canary on master). For beta, the explicit nightly version to promote (empty selects the newest nightly on master).required: falsetype: string+ candidate_branch:+ description: (beta) candidate/beta-* branch to build a cherry-picked beta from. Leave empty to promote a nightly. Mutually exclusive with source_version.+ required: false+ type: stringskip_soak_justification:description: (stable) Written justification for publishing a stable whose source has not soaked as a beta for 3 days. Leave empty for normal releases.required: false@@ -362,6 +366,7 @@ jobs:outputs:sha: ${{ steps.select.outputs.sha }}nightly_version: ${{ steps.select.outputs.nightly_version }}+ mode: ${{ steps.select.outputs.mode }}steps:- name: Checkout repositoryuses: actions/checkout@v7@@ -373,11 +378,65 @@ jobs:id: selectenv:EXPLICIT_NIGHTLY_VERSION: ${{ inputs.source_version }}+ CANDIDATE_BRANCH: ${{ inputs.candidate_branch }}run: |set -euo pipefailgit fetch origin --tags --prune --quiet+ # Candidate mode: build a cherry-picked beta from a short-lived+ # candidate branch instead of promoting a nightly.+ if [ -n "${CANDIDATE_BRANCH:-}" ]; then+ if [ -n "${EXPLICIT_NIGHTLY_VERSION:-}" ]; then+ echo "Error: candidate_branch and source_version are mutually exclusive." >&2+ exit 1+ fi+ case "$CANDIDATE_BRANCH" in+ candidate/beta-*) ;;+ *)+ echo "Error: candidate branches must be named candidate/beta-<target> (got: $CANDIDATE_BRANCH)." >&2+ exit 1+ ;;+ esac+ git fetch origin "$CANDIDATE_BRANCH" --quiet+ sha="$(git rev-parse --verify "origin/${CANDIDATE_BRANCH}^{commit}" 2>/dev/null || true)"+ if [ -z "$sha" ]; then+ echo "Error: candidate branch $CANDIDATE_BRANCH does not exist on origin." >&2+ exit 1+ fi++ existing_beta="$(git tag --points-at "$sha" | grep '^beta/v' | head -1 || true)"+ if [ -n "$existing_beta" ]; then+ echo "Error: candidate head $sha already shipped as $existing_beta." >&2+ exit 1+ fi++ if ! git show "${sha}:scripts/release.sh" | grep -qF -- '--from-candidate'; then+ echo "Error: candidate head $sha predates candidate-build release tooling; rebase the candidate onto a newer base." >&2+ exit 1+ fi++ merge_base="$(git merge-base origin/master "$sha")"+ echo "mode=candidate" >> "$GITHUB_OUTPUT"+ echo "sha=$sha" >> "$GITHUB_OUTPUT"+ echo "nightly_version=" >> "$GITHUB_OUTPUT"+ {+ echo "## Beta candidate branch"+ echo ""+ echo "- Branch: \`$CANDIDATE_BRANCH\`"+ echo "- Head: \`$sha\`"+ echo "- Base (merge-base with master): \`$merge_base\`"+ echo "- Cherry-picked commits:"+ echo ""+ echo '\`\`\`'+ git log --oneline "${merge_base}..${sha}"+ echo '\`\`\`'+ } >> "$GITHUB_STEP_SUMMARY"+ exit 0+ fi++ echo "mode=promote" >> "$GITHUB_OUTPUT"+if [ -n "${EXPLICIT_NIGHTLY_VERSION:-}" ]; thentag="nightly/v${EXPLICIT_NIGHTLY_VERSION}"sha="$(git rev-list -n 1 "$tag" 2>/dev/null || true)"@@ -425,8 +484,23 @@ jobs:echo "- Source nightly: \`$nightly_version\`"} >> "$GITHUB_STEP_SUMMARY"- publish_beta:+ # Candidate-branch heads are new commits that never went through a canary+ # or nightly, so they must pass full verification before publishing.+ # Promoted nightlies were already verified by their canary run and skip it.+ verify_beta_candidate:needs: select_beta+ if: needs.select_beta.outputs.mode == 'candidate'+ uses: ./.github/workflows/release-verify.yml+ with:+ ref: ${{ needs.select_beta.outputs.sha }}++ publish_beta:+ needs: [select_beta, verify_beta_candidate]+ if: >-+ !cancelled() &&+ needs.select_beta.result == 'success' &&+ (needs.verify_beta_candidate.result == 'success' ||+ (needs.verify_beta_candidate.result == 'skipped' && needs.select_beta.outputs.mode == 'promote'))runs-on: ubuntu-latesttimeout-minutes: 45environment: npm-beta@@ -480,6 +554,9 @@ jobs:GITHUB_ACTIONS: "true"run: |args=(beta --skip-verify)+ if [ "${{ needs.select_beta.outputs.mode }}" = "candidate" ]; then+ args+=(--from-candidate)+ fiif [ "${{ inputs.dry_run }}" = "true" ]; thenargs+=(--dry-run)fidiff --git a/doc/RELEASE-CHECKLIST.md b/doc/RELEASE-CHECKLIST.mdnew file mode 100644index 0000000000..3ab74932a8--- /dev/null+++ b/doc/RELEASE-CHECKLIST.md@@ -0,0 +1,72 @@+# Release Checklist++The release captain's checklist for every lane. The mechanics live in+[`RELEASING.md`](RELEASING.md); the user-facing channel guide is+[`CHANNELS.md`](CHANNELS.md).++## Canary (automatic, every `master` push)++- [ ] the push's `Release` run is green (verify + publish)+- [ ] `npm view paperclipai@canary version` matches the expected canary+- [ ] Docker `:canary` updated (the same push's `Docker` run)+- [ ] a canary publish failure is a release-infra regression — fix it before+ trusting later promotions++## Nightly (automatic, 09:00 UTC)++- [ ] the scheduled run selected the newest green canary, or skipped with a+ job-summary reason (no new candidate / already shipped / red smoke)+- [ ] the release smoke suite passed against the exact candidate canary+ before anything published+- [ ] `npm view paperclipai@nightly version` shows the new `-nightly.N`+- [ ] `nightly/v*` tag pushed; `:nightly` and `:nightly-cloud` images built+- [ ] on a tag-push rejection (workflows-permission error), follow the+ recovery commands in the job summary++To force a nightly: dispatch `release.yml` with `channel: nightly`+(optional exact canary in `source_version`; `dry_run` to preview).++## Beta (manual promotion)++Happy path:++- [ ] pick the nightly to promote (empty `source_version` selects the newest)+- [ ] dispatch `release.yml` with `channel: beta`+- [ ] approve the `npm-beta` environment gate+- [ ] `npm view paperclipai@beta version` shows the new `-beta.N`+- [ ] `beta/v*` tag pushed; `:beta` and `:beta-cloud` images built+- [ ] post-publish smoke (`smoke_beta`) is green++Fix path (cherry-picked candidate):++- [ ] cut `candidate/beta-<target>` from the chosen nightly's source commit+- [ ] cherry-pick only the required fixes; push the branch+- [ ] dispatch `channel: beta` with `candidate_branch`+- [ ] confirm the job summary records the cherry-picked commits and that+ full verification ran on the candidate head+- [ ] after shipping: reconcile the fixes to `master`, delete the branch++## Stable (manual promotion)++- [ ] pick the beta to promote; its source commit is `source_ref`+- [ ] the beta has soaked ≥ 3 days with no open beta-blocker issues+- [ ] author `releases/vYYYY.MDD.P.md` on that source ref+- [ ] dispatch `release.yml` with `channel: stable` (a dry run first shows+ the resolved version and soak state without publishing)+- [ ] approve the `npm-stable` environment gate+- [ ] `npm view paperclipai version` (dist-tag `latest`) shows the stable+- [ ] `vYYYY.MDD.P` tag pushed; GitHub Release created; `:latest` and the+ versioned Docker tags built+- [ ] if the soak gate was bypassed, `skip_soak_justification` carries a+ real written reason (it lands in the job summary)++Fix path: `candidate/release-<target>` from the beta's source commit; the+soak gate will demand a justification because the exact bits were not+soaked — write one that stands on its own.++## After any incomplete run++The failure playbooks in [`RELEASING.md`](RELEASING.md) cover: red canary,+skipped or failed nightly, a beta that looks bad during soak, partial+stable releases, broken `latest`, and rejected tag pushes. Every publish+job's summary names what completed and what remains.diff --git a/doc/RELEASING.md b/doc/RELEASING.mdindex f6f3e6d41c..1e1891663d 100644--- a/doc/RELEASING.md+++ b/doc/RELEASING.md@@ -166,6 +166,28 @@ Users install betas with:npx paperclipai@beta onboard```+#### Beta fix path: candidate branches++When one or two targeted fixes are needed before beta and waiting for the+next nightly (or absorbing a whole day of `master`) is wrong, build the beta+from a short-lived candidate branch:++1. cut `candidate/beta-<target>` from the chosen nightly's source commit+ (for example `candidate/beta-2026.811.0`)+2. cherry-pick only the required fix commits onto it and push the branch+3. dispatch `release.yml` with `channel: beta` and `candidate_branch:+ candidate/beta-<target>`+4. selection validates the branch name, rejects heads that already shipped+ as a beta, records the cherry-picked commits in the job summary, and the+ head runs **full verification** before publishing (it never went through+ a canary or nightly)+5. after the beta ships, land the fixes on `master` normally and delete the+ candidate branch++Use this sparingly: the happy path is promoting a nightly. A candidate build+has its own `-beta.N` identity and is never pretended to be the nightly it+was cut from.+### StableUse [`.github/workflows/release.yml`](../.github/workflows/release.yml) from the Actions tab with the manual `workflow_dispatch` inputs.@@ -193,6 +215,14 @@ The stable preflight enforces the beta soak: the source commit must carry athe run fails unless `skip_soak_justification` is provided; the justificationis echoed into the job summary. Dry runs report soak state without blocking.+For a cherry-picked stable (the release fix path), cut+`candidate/release-<target>` from the chosen beta's source commit,+cherry-pick the required fixes, push the branch, and use it as+`source_ref`. The candidate head carries no `beta/v*` tag, so the soak gate+requires `skip_soak_justification` — that is deliberate: the exact bits were+not soaked, and the justification is the recorded trade-off. Reconcile the+fixes back to `master` and delete the branch after shipping.+Before running stable:1. pick the beta you are promoting (its source commit is the `source_ref`)@@ -429,5 +459,6 @@ Then fix forward with a new stable release.- [`scripts/release-package-map.mjs`](../scripts/release-package-map.mjs)- [`scripts/create-github-release.sh`](../scripts/create-github-release.sh)- [`scripts/rollback-latest.sh`](../scripts/rollback-latest.sh)+- [`doc/RELEASE-CHECKLIST.md`](RELEASE-CHECKLIST.md)- [`doc/PUBLISHING.md`](PUBLISHING.md)- [`doc/RELEASE-AUTOMATION-SETUP.md`](RELEASE-AUTOMATION-SETUP.md)diff --git a/scripts/__tests__/release-dry-run-notes.test.mjs b/scripts/__tests__/release-dry-run-notes.test.mjsindex 64f70fcc0f..6f1d12d003 100644--- a/scripts/__tests__/release-dry-run-notes.test.mjs+++ b/scripts/__tests__/release-dry-run-notes.test.mjs@@ -218,6 +218,26 @@ test("beta refuses commits that already shipped as a beta", () => {assert.doesNotMatch(result.calls, /^pnpm /m);});+test("beta --from-candidate waives the nightly requirement but keeps the duplicate guard", () => {+ const result = runRelease(["beta", "--from-candidate", "--skip-verify", "--dry-run"], {+ FAKE_MISSING_CHANNEL_TAG: "nightly",+ });++ assert.equal(result.status, 42);+ assert.doesNotMatch(result.output, /require_channel_tag_at_head nightly/);+ assert.match(result.output, /\[fixture\] require_channel_tag_absent_at_head beta/);+ assert.match(result.output, /Beta version: 2026\.710\.0-beta\.0/);+ assert.match(result.calls, /^pnpm build$/m);+});++test("--from-candidate is rejected outside the beta channel", () => {+ const result = runRelease(["nightly", "--from-candidate", "--skip-verify", "--dry-run"]);++ assert.equal(result.status, 1);+ assert.match(result.output, /--from-candidate only applies to the beta channel/);+ assert.doesNotMatch(result.calls, /^pnpm /m);+});+test("beta refuses commits that never shipped a nightly", () => {const result = runRelease(["beta", "--skip-verify", "--dry-run"], {FAKE_MISSING_CHANNEL_TAG: "nightly",diff --git a/scripts/__tests__/release-verify-workflow.test.mjs b/scripts/__tests__/release-verify-workflow.test.mjsindex df30f9e953..354bd81c4c 100644--- a/scripts/__tests__/release-verify-workflow.test.mjs+++ b/scripts/__tests__/release-verify-workflow.test.mjs@@ -47,6 +47,19 @@ test("promotion selection guards against sources that predate their channel toolassert.match(releaseWorkflow, /git show "\$\{sha\}:scripts\/release\.sh" \| grep -qF 'canary\|nightly\|beta\|stable\)'/);});+test("candidate-branch betas are validated and fully verified before publish", () => {+ const releaseWorkflow = readWorkflow("release.yml");++ // Candidate heads are new commits: selection must pin the naming+ // convention and publication must be gated on full verification.+ assert.match(releaseWorkflow, /candidate\/beta-\*\)/);+ assert.match(+ releaseWorkflow,+ /verify_beta_candidate:\n\s+needs: select_beta\n\s+if: needs\.select_beta\.outputs\.mode == 'candidate'\n\s+uses: \.\/\.github\/workflows\/release-verify\.yml/,+ );+ assert.match(releaseWorkflow, /needs\.verify_beta_candidate\.result == 'success'/);+});+test("every lane's tag push degrades to recovery instructions when rejected", () => {const releaseWorkflow = readWorkflow("release.yml");diff --git a/scripts/release.sh b/scripts/release.shindex db3a4ea90a..5d51aab69a 100755--- a/scripts/release.sh+++ b/scripts/release.sh@@ -11,6 +11,7 @@ release_date=""dry_run=falseskip_verify=falseprint_version_only=false+from_candidate=falsetag_name=""cleanup_on_exit=false@@ -25,6 +26,7 @@ Examples:./scripts/release.sh canary --date 2026-03-17 --dry-run./scripts/release.sh nightly --dry-run./scripts/release.sh beta --dry-run+ ./scripts/release.sh beta --from-candidate --dry-run./scripts/release.sh stable./scripts/release.sh stable --date 2026-03-17 --dry-run./scripts/release.sh stable --date 2026-03-18 --print-version@@ -41,6 +43,9 @@ Notes:- Beta releases republish a commit that already shipped a nightly (HEADmust carry a nightly/v* tag) as YYYY.MDD.P-beta.N under the npmdist-tag "beta", with the git tag beta/vYYYY.MDD.P-beta.N.+ - --from-candidate (beta only) waives the nightly-tag requirement for+ cherry-picked candidate-branch builds; callers are responsible for+ validating the candidate branch before using it.- Stable releases publish YYYY.MDD.P under the npm dist-tag "latest" andcreate the git tag vYYYY.MDD.P.- Non-dry-run stable release notes must already exist at releases/vYYYY.MDD.P.md.@@ -108,6 +113,7 @@ while [ $# -gt 0 ]; do--dry-run) dry_run=true ;;--skip-verify) skip_verify=true ;;--print-version) print_version_only=true ;;+ --from-candidate) from_candidate=true ;;-h|--help)usageexit 0@@ -124,6 +130,10 @@ doneexit 1}+if [ "$from_candidate" = true ] && [ "$channel" != "beta" ]; then+ release_fail "--from-candidate only applies to the beta channel."+fi+PUBLISH_REMOTE="$(resolve_release_remote)"fetch_release_remote "$PUBLISH_REMOTE"@@ -167,8 +177,15 @@ elif [ "$channel" = "nightly" ]; thenDIST_TAG="nightly"tag_name="$(prerelease_tag_name nightly "$TARGET_PUBLISH_VERSION")"elif [ "$channel" = "beta" ]; then- # Beta promotes an already-shipped nightly commit.- require_channel_tag_at_head nightly+ if [ "$from_candidate" = true ]; then+ # Candidate builds carry targeted cherry-picks that never shipped as a+ # nightly, so the nightly-tag requirement does not apply; the workflow+ # validates the candidate branch identity before invoking this path.+ :+ else+ # Beta promotes an already-shipped nightly commit.+ require_channel_tag_at_head nightly+ firequire_channel_tag_absent_at_head betaTARGET_PUBLISH_VERSION="$(next_prerelease_version beta "$TARGET_STABLE_VERSION" "${PUBLIC_PACKAGE_NAMES[@]}")"DIST_TAG="beta"