diff --git a/.github/workflows/release-bugfix.yml b/.github/workflows/release-bugfix.yml index 9859efeec6..cf62eb5326 100644 --- a/.github/workflows/release-bugfix.yml +++ b/.github/workflows/release-bugfix.yml @@ -1,31 +1,44 @@ name: Bugfix Release (carve-out) -# Dedicated emergency / hotfix publish channel (#2011). +# Dedicated emergency / hotfix publish channel (#2011), PR-gated since #2851. # # Publishes a version cut from a NON-master ref -- e.g. a released tag plus a # single fix -- STRICTLY excluding the unreleased work that has since -# accumulated on master. This is the mechanism the owner requested for the -# v0.1.182 emergency: ship ONLY the integer max_tokens fix without dragging in -# the ~70 commits already merged to master after v0.1.181. +# accumulated on master. First used for the v0.1.182 emergency: ship ONLY the +# integer max_tokens fix without dragging in the ~70 commits already merged to +# master after v0.1.181. # # Unlike release.yml (which builds the POST-MERGE MASTER tree on push-to-master, # so it can never exclude master's existing commits), this checks out and -# publishes the pushed/dispatched REF itself -- the artifact is exactly that -# ref's tree, nothing else. +# publishes the CARVE-OUT PR HEAD tree itself -- the artifact is exactly that +# tree, nothing else. # -# Triggered ONLY by pushes to branches under `bugfix-release/**`, or a manual -# workflow_dispatch against such a ref. Guarded so it can never: +# GATE MODEL (#2851): the carve-out branch is opened as a PR against master and +# publishes ONLY when that PR is MERGED -- the same human review gate as every +# normal release. Pushing a bugfix-release/** branch triggers NOTHING (the old +# silent-push auto-publish was removed). The head branch keeps the +# bugfix-release/ prefix as the carve-out MARKER: release.yml's detection +# deliberately does not match it, so merging the PR cannot double-publish the +# post-merge master through the normal channel. +# +# Emergency fallback: manual workflow_dispatch against an explicitly chosen ref +# (a human picks the exact ref in the Actions UI; every guard below still runs). +# +# Guarded so it can never: # - move `latest` backwards (target must be strictly newer than npm latest); # - re-publish an already-live version; # - ship a sub-0.1.0 line (#1385); -# - publish a stable version with no release-notes entry (#1870). +# - publish a stable version with no release-notes entry (#1870); +# - act on fork PRs (secrets unavailable) or on non-merged closes. # -# It does NOT touch master: no merge, no direct push to master. The tag points -# at the hotfix ref; master advances independently on its next normal release. +# Master interaction: merging the carve-out PR brings the version bump INTO +# master (master then equals npm latest). Master advances independently on its +# next normal release, which MUST be higher than the carve-out version. on: - push: - branches: [ 'bugfix-release/**' ] + pull_request: + types: [closed] + branches: [master] workflow_dispatch: inputs: {} @@ -41,17 +54,59 @@ jobs: id-token: write actions: write steps: - - uses: actions/checkout@v4 + - name: Validate trigger + resolve the publish ref + id: resolve + run: | + if [ "$GITHUB_EVENT_NAME" = "pull_request" ]; then + MERGED="$(jq -r '.pull_request.merged' "$GITHUB_EVENT_PATH")" + BRANCH="$(jq -r '.pull_request.head.ref' "$GITHUB_EVENT_PATH")" + SAME_REPO="$(jq -r '(.pull_request.base.repo.full_name == .pull_request.head.repo.full_name)' "$GITHUB_EVENT_PATH")" + SHA="$(jq -r '.pull_request.head.sha' "$GITHUB_EVENT_PATH")" + if [ "$MERGED" != "true" ]; then + echo "::notice::PR $GITHUB_EVENT_NUMBER closed without merging — nothing to publish" + exit 0 + fi + case "$BRANCH" in + bugfix-release/*) ;; + *) + echo "::notice::head branch '$BRANCH' is not a bugfix-release/* carve-out branch — nothing to publish" + exit 0 + ;; + esac + if [ "$SAME_REPO" != "true" ]; then + echo "::error::fork PRs cannot use the carve-out channel (repo secrets are unavailable for them)" + exit 1 + fi + else + BRANCH="$GITHUB_REF_NAME" + SHA="" + fi + echo "branch=$BRANCH" >> "$GITHUB_OUTPUT" + echo "sha=$SHA" >> "$GITHUB_OUTPUT" + echo "proceed=true" >> "$GITHUB_OUTPUT" + + - name: Checkout + if: steps.resolve.outputs.proceed == 'true' + uses: actions/checkout@v4 with: fetch-depth: 0 + - name: Switch to the carve-out PR head (pre-merge tree) + if: steps.resolve.outputs.proceed == 'true' && github.event_name == 'pull_request' + run: | + SHA="${{ steps.resolve.outputs.sha }}" + git rev-parse --verify --quiet "${SHA}^{commit}" >/dev/null || git fetch origin "$SHA" + git checkout --detach "$SHA" + - uses: actions/setup-node@v4 + if: steps.resolve.outputs.proceed == 'true' with: node-version: 22 registry-url: https://registry.npmjs.org - name: Read version id: version + if: steps.resolve.outputs.proceed == 'true' run: | V="$(node -p "require('./package.json').version")" case "$V" in @@ -61,9 +116,13 @@ jobs: ;; esac echo "version=$V" >> $GITHUB_OUTPUT - echo "::notice::Publishing carve-out from ref '${GITHUB_REF_NAME}' @ ${GITHUB_SHA} -> v$V (master NOT involved)" + REF="${{ steps.resolve.outputs.branch }}" + SHA="${{ steps.resolve.outputs.sha }}" + [ -z "$SHA" ] && SHA="$(git rev-parse HEAD)" + echo "::notice::Publishing carve-out from '$REF' @ ${SHA:0:12} -> v$V (master NOT involved)" - name: Publish guard (monotonic + not-already-live) + if: steps.resolve.outputs.proceed == 'true' run: | VER="${{ steps.version.outputs.version }}" LATEST="$(npm view billion-context version)" @@ -88,6 +147,7 @@ jobs: # declarations — only severe releases need one; ordinary releases ship # silently with NO entry. Missing entry => notice + pass; present # entry => validated and logged. + if: steps.resolve.outputs.proceed == 'true' run: | VER="${{ steps.version.outputs.version }}" case "$VER" in @@ -106,18 +166,23 @@ jobs: - name: Full CI dispatch (all lanes, publish sha) # Policy (2026-10-10, after the v0.1.192 carve-out): every release # channel must run the COMPLETE CI set at the exact publish sha before - # npm publish. This channel has no PR, so nothing else runs CI on this - # sha — dispatch every lane that has no run here (idempotent); the - # Full CI gate step after the pre-flight blocks publish until green. + # npm publish. In the PR-gated flow the lanes already ran on the PR + # head sha (path-filtered pull_request triggers) — dispatch only what + # has no run there (idempotent); the Full CI gate after the pre-flight + # blocks publish until green. + if: steps.resolve.outputs.proceed == 'true' env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | - GITHUB_SHA="$(git rev-parse HEAD)" + GITHUB_SHA="${{ steps.resolve.outputs.sha }}" + [ -z "$GITHUB_SHA" ] && GITHUB_SHA="$(git rev-parse HEAD)" export GITHUB_SHA + export GITHUB_REF_NAME="${{ steps.resolve.outputs.branch }}" node scripts/release-ci-gate.mjs --dispatch - name: Pre-flight gate # keep the claude-native live e2e subtests in this pre-publish gate (#1248) + if: steps.resolve.outputs.proceed == 'true' env: ACP_TEST_CLAUDE_NATIVE: "1" run: | @@ -127,19 +192,24 @@ jobs: npm run build - name: Full CI gate (all lanes green at this sha) - # Hard precondition for publish: lanes dispatched above ran in - # parallel with the pre-flight; wait them out now. Any red lane or - # timeout ⇒ release fails, nothing is published. + # Hard precondition for publish: lanes dispatched above (plus the PR's + # own lane runs at the head sha) ran in parallel with the pre-flight; + # wait them out now. Any red lane or timeout ⇒ release fails, nothing + # is published. + if: steps.resolve.outputs.proceed == 'true' env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} CI_GATE_TIMEOUT_MIN: "60" run: | - GITHUB_SHA="$(git rev-parse HEAD)" + GITHUB_SHA="${{ steps.resolve.outputs.sha }}" + [ -z "$GITHUB_SHA" ] && GITHUB_SHA="$(git rev-parse HEAD)" export GITHUB_SHA + export GITHUB_REF_NAME="${{ steps.resolve.outputs.branch }}" node scripts/release-ci-gate.mjs --wait - name: Check if prerelease id: pre + if: steps.resolve.outputs.proceed == 'true' run: | if echo "${{ steps.version.outputs.version }}" | grep -q '-'; then echo "tag=dev" >> $GITHUB_OUTPUT @@ -150,6 +220,7 @@ jobs: fi - name: Create tag + if: steps.resolve.outputs.proceed == 'true' run: | git config user.name "github-actions[bot]" git config user.email "github-actions[bot]@users.noreply.github.com" @@ -157,11 +228,13 @@ jobs: git push origin "v${{ steps.version.outputs.version }}" || true - name: Publish + if: steps.resolve.outputs.proceed == 'true' run: npm publish --tag ${{ steps.pre.outputs.tag }} --access public env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} - name: Create GitHub Release + if: steps.resolve.outputs.proceed == 'true' env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | diff --git a/AGENTS.md b/AGENTS.md index cbb94f3918..502d9f264e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -181,7 +181,7 @@ Releases are fully automated via CI (`.github/workflows/release.yml`): the Agent - **Branch** `YYYY-MM-DD_release-v{VERSION}`; commit `release v{VERSION}` changing ONLY `version`. The Agent does steps 1–6 (sync master → branch → bump → **release-notes entry if severe (#1870)** → pre-flight typecheck+test+build → commit/push/open PR); HUMAN merges step 7; CI publishes step 8. - **Release-notes entry (#1870, OPT-IN since 2026-10-04):** only SEVERE releases need an entry in `release-notes/package.json`; ordinary releases ship with NO entry (the gates log a notice and pass when absent, validate when present). Add a severe entry as its own commit in the SAME release PR; the one-click fast path needs it already merged to master before dispatching. Full rules: [reference/release.md](reference/release.md) + `release-notes/README.md`. -- **Bugfix carve-out channel (#2011):** emergency hotfixes ship through `.github/workflows/release-bugfix.yml` (dispatch-triggered, no release branch) — mechanics and constraints: [reference/release.md](reference/release.md). +- **Bugfix carve-out channel (#2011, PR-gated since #2851):** emergency hotfixes ship as a normal-looking release PR whose head branch keeps the `bugfix-release/v{VERSION}-{slug}` marker (cut from the last released TAG, containing ONLY the fix + version bump); merging it publishes the PRE-MERGE PR-head tree — strictly excluding master's other unreleased work. Pushing such a branch triggers nothing anymore; a manual `workflow_dispatch` on an explicitly chosen ref remains the emergency fallback. Mechanics and constraints: [reference/release.md](reference/release.md). - **NEVER run `npm publish` manually** — CI does it (§4). - **Kernel releases (separate artifact, #2092).** `acp-kernel` can be published standalone from this repo when accumulated kernel changes warrant it: branch `YYYY-MM-DD_release-kernel-v{VERSION}`, commit `release kernel v{VERSION}` changing ONLY the version in `kernel/package.json`. Merging runs `.github/workflows/release-kernel.yml`: full bili gate + kernel suite, publish `acp-kernel` to npm, tag `kernel-v{VERSION}` (separate tag namespace — bili tags stay bare `v*`), GitHub Release. No release-notes entry required (different artifact; the PR body serves as notes). The two branch patterns are mutually exclusive, so bili's and kernel's release flows never cross-trigger. Downstream consumers of the npm package update as usual — zero notice needed. - **Changing `src/update.ts` (the updater itself) requires a NO-OP validation release FIRST** — a pure version bump proves the *existing* upgrade path is healthy end-to-end before the change ships. A broken updater bricks every future upgrade. Full protocol + rationale: [reference/release.md](reference/release.md). diff --git a/reference/release.md b/reference/release.md index a6225a4338..b4d5c82314 100644 --- a/reference/release.md +++ b/reference/release.md @@ -144,46 +144,63 @@ gate). ## Bugfix carve-out channel (release-bugfix.yml) -Emergency hotfix path (#2011, first used for v0.1.182): publish a version cut from -a **non-master ref** — typically a released tag plus a single fix commit — STRICTLY -excluding the unreleased work that has since accumulated on master. +Emergency hotfix path (#2011, first used for v0.1.182), **PR-gated since #2851**: +publish a version cut from a **non-master ref** — typically a released tag plus a +single fix commit — STRICTLY excluding the unreleased work that has since +accumulated on master. It goes through a PR exactly like a normal release (human +reviews and merges; CI publishes); the ONLY difference is the published tree: the +PRE-MERGE PR-head tree (last tag + the fix + the version bump), never the +post-merge master. `release.yml` cannot do this: it builds the post-merge MASTER tree on push-to-master, so it can never exclude commits already on master. This channel checks out and -publishes the pushed/dispatched REF itself — the artifact is exactly that ref's tree, +publishes the carve-out PR's head tree instead — the artifact is exactly that tree, nothing else. **Process:** 1. Cut the hotfix branch from the last released TAG (not master), apply ONLY the fix - plus the version bump (plus the release-notes entry ONLY if the hotfix is - severe — step 4 above), then push: + plus the version bump (regenerate `package-lock.json` as in step 3 above; plus the + release-notes entry ONLY if the hotfix is severe — step 4 above), then push and + open a PR against master: ```bash git checkout -b bugfix-release/v{VERSION}-{slug} v{LAST-RELEASED-TAG} ``` - The `bugfix-release/` name prefix is the trigger (`push`, or manual dispatch - against such a ref); concurrency group `bugfix-release`, no cancel-in-progress. -2. The run reads the target version from the ref's `package.json` (before any gate) - and enforces fail-closed guards: + The `bugfix-release/` name prefix is the carve-out MARKER, not a trigger: pushing + such a branch no longer auto-publishes (#2851 removed the silent-push path). It is + what `release.yml`'s detection deliberately does NOT match, so merging the PR + cannot double-publish the post-merge master through the normal channel. +2. **Human reviews and merges the PR** — the same review gate as a normal release + PR. While it is open, the standard lane set already runs on the head sha + (path-filtered `pull_request` triggers), which the publish gate reuses. +3. On merge, `release-bugfix.yml` (`pull_request` closed trigger) validates + (merged, same-repo head, `bugfix-release/*` branch), checks out the PRE-MERGE PR + head tree, reads the target version from its `package.json` (before any gate) and + enforces fail-closed guards: - strictly newer than npm latest (base-semver compare — never holds or downgrades `latest`; conservative edge: a stable `X` is refused while npm latest is `X-dev`); - not already published (`npm view billion-context@$VER`); - no sub-0.1.0 lines (#1385); - severe stable versions need a release-notes entry ON THE REF (#1870; ordinary releases ship with none; prereleases exempt). -3. Full pre-flight gate before publish: `npm ci` + typecheck + test + build - (`ACP_TEST_CLAUDE_NATIVE=1`, #1248). -4. Publishes `--tag latest` (`dev` for prereleases), pushes tag `v{VERSION}`, creates +4. Full pre-flight gate before publish: `npm ci` + typecheck + test + build + (`ACP_TEST_CLAUDE_NATIVE=1`, #1248), plus the full-CI gate at the publish sha + (reusing the PR's own green lane runs where they exist). +5. Publishes `--tag latest` (`dev` for prereleases), pushes tag `v{VERSION}`, creates the GitHub Release with notes generated from `git log` between the nearest ancestor tag other than the one just made and HEAD — for a tag+one-fix carve-out that list is exactly the fix (deliberately NOT `generate_release_notes:true`, which would span into unreleased master work). -**Master stays out:** no merge, no push to master, no interaction with the standard -flow. The tag points at the hotfix ref; master keeps its own (older) version and -advances independently on its next normal release, which MUST be higher than the -carve-out version (after v0.1.182 was cut off v0.1.181, master stayed 0.1.181 → next -normal release ≥ 0.1.183). +**Emergency fallback:** a manual `workflow_dispatch` run against an explicitly chosen +ref (picked in the Actions UI) still works and runs every guard above — for when the +PR dance is slower than the fire. + +**Master interaction:** merging the carve-out PR brings the version bump INTO master +(master then equals npm latest, so the one-click fast path's drift guard sees a clean +tree again). Master advances independently on its next normal release, which MUST be +higher than the carve-out version (after v0.1.182 was cut off v0.1.181, the next +normal release must be ≥ 0.1.183). ## CI publish mechanism (what release.yml does)