Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
119 changes: 96 additions & 23 deletions .github/workflows/release-bugfix.yml
Original file line number Diff line number Diff line change
@@ -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: {}

Expand All @@ -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
Expand All @@ -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)"
Expand All @@ -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
Expand All @@ -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: |
Expand All @@ -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
Expand All @@ -150,18 +220,21 @@ 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"
git tag "v${{ steps.version.outputs.version }}" || true
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: |
Expand Down
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
53 changes: 35 additions & 18 deletions reference/release.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down
Loading