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
168 changes: 168 additions & 0 deletions .github/workflows/release-bugfix.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,168 @@
name: Bugfix Release (carve-out)

# Dedicated emergency / hotfix publish channel (#2011).
#
# 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.
#
# 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.
#
# Triggered ONLY by pushes to branches under `bugfix-release/**`, or a manual
# workflow_dispatch against such a ref. 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).
#
# 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.

on:
push:
branches: [ 'bugfix-release/**' ]
workflow_dispatch:
inputs: {}

concurrency:
group: bugfix-release
cancel-in-progress: false

jobs:
release:
runs-on: ubuntu-latest
permissions:
contents: write
id-token: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0

- uses: actions/setup-node@v4
with:
node-version: 22
registry-url: https://registry.npmjs.org

- name: Read version
id: version
run: |
V="$(node -p "require('./package.json').version")"
case "$V" in
0.0.*)
echo "::error::package.json version $V is below 0.1.0 — official releases must always sort above the 0.0.x PR-build line (#1385)"
exit 1
;;
esac
echo "version=$V" >> $GITHUB_OUTPUT
echo "::notice::Publishing carve-out from ref '${GITHUB_REF_NAME}' @ ${GITHUB_SHA} -> v$V (master NOT involved)"

- name: Publish guard (monotonic + not-already-live)
run: |
VER="${{ steps.version.outputs.version }}"
LATEST="$(npm view billion-context version)"
if [ -z "$LATEST" ]; then
echo "::error::cannot read npm latest for billion-context"; exit 1
fi
LIVE="$(npm view "billion-context@$VER" version 2>/dev/null || true)"
if [ "$LIVE" = "$VER" ]; then
echo "::error::$VER is already published on npm; pick a newer version"; exit 1
fi
node -e '
const base = (s) => s.split("-")[0].split(".").map(Number);
const cmp = (a,b) => { for (let i=0;i<3;i++){ if(a[i]!==b[i]) return a[i]-b[i]; } return 0; };
const v = process.argv[1], l = process.argv[2];
const c = cmp(base(v), base(l));
if (c <= 0) { console.error("::error::target " + v + " is not strictly newer than npm latest " + l + " — refusing to hold/downgrade latest"); process.exit(1); }
console.log("guard ok: " + v + " > latest " + l);
' "$VER" "$LATEST"

- name: Verify release-notes entry (#1870)
run: |
VER="${{ steps.version.outputs.version }}"
case "$VER" in
*-*) echo "prerelease $VER — release-notes gate skipped"; exit 0 ;;
esac
node -e "
const notes = require('./release-notes/package.json').billionContextReleaseNotes;
const entry = notes && notes.releases && notes.releases.find((e) => e.version === process.argv[1]);
if (!entry) {
console.error('::error::release ' + process.argv[1] + ' has no release-notes entry (tier + model-written summary). Add it to release-notes/package.json BEFORE dispatching — see release-notes/README.md (#1870).');
process.exit(1);
}
console.log('release-notes entry ok:', entry.version, '[' + entry.tier + ']', entry.summary.slice(0, 80));
" "$VER"

- name: Pre-flight gate
# keep the claude-native live e2e subtests in this pre-publish gate (#1248)
env:
ACP_TEST_CLAUDE_NATIVE: "1"
run: |
npm ci
npm run typecheck
npm test
npm run build

- name: Check if prerelease
id: pre
run: |
if echo "${{ steps.version.outputs.version }}" | grep -q '-'; then
echo "tag=dev" >> $GITHUB_OUTPUT
echo "prerelease=true" >> $GITHUB_OUTPUT
else
echo "tag=latest" >> $GITHUB_OUTPUT
echo "prerelease=false" >> $GITHUB_OUTPUT
fi

- name: Create tag
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
run: npm publish --tag ${{ steps.pre.outputs.tag }} --access public
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

- name: Create GitHub Release
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
VER="${{ steps.version.outputs.version }}"
# nearest ancestor tag other than the one we just made (=> v0.1.181 for this carve-out)
LAST="$(git describe --match 'v*' --exclude "v$VER*" --tags --abbrev=0 2>/dev/null || echo "")"
NOTES="$RUNNER_TEMP/release-notes.md"
if [ -n "$LAST" ] && [ "$LAST" != "v$VER" ]; then
{
echo "## Changes since $LAST"
echo ""
git log --no-merges --pretty='- %s' "$LAST..HEAD"
} > "$NOTES"
else
echo "- initial release" > "$NOTES"
fi
node -e '
const fs = require("fs");
const [notesFile, ver, prerelease, out] = process.argv.slice(1);
const body = {
tag_name: "v" + ver,
name: "v" + ver,
prerelease: prerelease === "true",
body: fs.readFileSync(notesFile, "utf8").trim()
};
fs.writeFileSync(out, JSON.stringify(body));
' "$NOTES" "$VER" "${{ steps.pre.outputs.prerelease }}" "$RUNNER_TEMP/release.json"
curl -sS -f -X POST \
-H "Authorization: Bearer $GH_TOKEN" \
-H "Accept: application/vnd.github+json" \
-H "X-GitHub-Api-Version: 2022-11-28" \
-H "Content-Type: application/json" \
"https://api.github.com/repos/${{ github.repository }}/releases" \
-d @"$RUNNER_TEMP/release.json"
2 changes: 1 addition & 1 deletion reference/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ is loaded every session. The split is deliberate and load-bearing:
|------|-------|------------------|
| [architecture.md](architecture.md) | The file-by-file `src/` module map + orientation cheat-sheet | Adding/removing a module, or needing to find where a concern lives. Regenerate the map when it drifts. |
| [testing.md](testing.md) | Build commands, local install, E2E codex + image-billing + hermetic-registry (+ advisory-rollback) suites (env vars, phases, CI trigger list) | Running build/test/e2e or wiring a test. |
| [release.md](release.md) | Release process steps (incl. release-notes entry), one-click workflow internals, cross-repo acp-kernel ordering, auto-update testing, no-op validation protocol | Preparing or reviewing a release. |
| [release.md](release.md) | Release process steps (incl. release-notes entry), one-click workflow internals, bugfix carve-out channel, cross-repo acp-kernel ordering, auto-update testing, no-op validation protocol | Preparing or reviewing a release, or cutting an emergency hotfix. |
| [git-pr.md](git-pr.md) | "Open a PR without `gh`" REST recipe; external-contributor PR mechanics; post-merge supplements | Opening a PR or handling a contributor's PR. |

> If you add a new reference file, add a row above and a pointer from the relevant
Expand Down
41 changes: 41 additions & 0 deletions reference/release.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,6 +128,47 @@ commit. The standard branch/PR flow above remains the canonical path for anythin
non-trivial (updater changes, cross-repo bumps, or whenever a human wants the review
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.

`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,
nothing else.

**Process:**

1. Cut the hotfix branch from the last released TAG (not master), apply ONLY the fix
plus the version bump and the release-notes entry (step 4 above), then push:
```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:
- 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);
- stable versions need a release-notes entry ON THE REF (#1870; 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
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).

## CI publish mechanism (what release.yml does)

- **Trigger**: push to `master` where the merge commit or branch name matches
Expand Down
8 changes: 7 additions & 1 deletion release-notes/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,14 @@
},
"billionContextReleaseNotes": {
"schema": 1,
"updated": "2026-10-03",
"updated": "2026-10-04",
"releases": [
{
"version": "0.1.182",
"date": "2026-10-04",
"tier": "recommended",
"summary": "Emergency carve-out: the output-budget clamp now floors to an integer, so max_tokens / max_completion_tokens / max_output_tokens are always whole numbers. Strict OpenAI-compatible upstreams no longer reject requests with 'max_tokens: Input should be a valid integer' (400) or 'Endpoint is unavailable' (422) — which killed whole agent turns (#2011). Only this fix, on top of v0.1.181."
},
{
"version": "0.1.181",
"date": "2026-10-03",
Expand Down
Loading