- verdaccio LAN IP -> <verdaccio-LAN-IP> placeholder (release.md checklist) - private VM runbook path -> generic wording - relay knob docs: drop provider identity + auth notes, keep semantics
19 KiB
Release Workflow Reference
Not auto-loaded. On-demand mechanics pulled out of
AGENTS.md§5 to keep the auto-loaded spec lean. The hard rules (never manual publish, version-only-on-release-branch, kernel changes are human-gated, updater changes need a no-op release first) stay inAGENTS.md§5; this file holds the exact steps, the one-click workflow internals, and the no-op validation protocol.
Releases are fully automated via CI (.github/workflows/release.yml; kernel
releases use .github/workflows/release-kernel.yml). The Agent prepares a release PR;
merging it triggers CI which builds, tests, publishes to npm, creates a git tag, and
creates a GitHub Release. For routine patch releases there is also a one-click fast
path below.
Branch Naming
Release branches: YYYY-MM-DD_release-v{VERSION} (e.g., 2026-08-08_release-v0.1.17)
Kernel release branches: YYYY-MM-DD_release-kernel-v{VERSION} (e.g. 2026-11-01_release-kernel-v0.0.102) — see "Kernel releases" below.
Process (exact steps)
The Agent does steps 1–6, the human does step 7 (merge).
- Sync master:
git checkout master && git pull --ff-only origin master - Create the release branch from master:
git checkout -b $(date +%Y-%m-%d)_release-v{VERSION} - Bump version — edit ONLY the
"version"field inpackage.json:Then regenerate the lock so its root +- "version": "0.1.16", + "version": "0.1.17",file:-link version fields track the bump — editingpackage.jsonalone does NOT touchpackage-lock.json(#2704):CI enforces this with thenpm install --package-lock-only --ignore-scripts --no-fund --no-audit git diff --exit-code -- package-lock.json # must be clean before you commitlock-syncguard (ci.yml). - Add the release-notes entry — ONLY for severe releases (#1870, opt-in
since 2026-10-04) — ordinary releases skip this step entirely and ship
with NO entry. When a release IS severe, add the entry in the SAME release
PR, as its own commit (never bundled into the release commit): prepend an
entry to the
releasesarray inrelease-notes/package.json:{ "version": "0.1.17", "date": "2026-08-08", "tier": "recommended", "summary": "what changes FOR THE USER, one line, issue/PR refs" }tier:routine(default) |recommended(restart-soon record — correctness/cache/self-heal fixes; NOT user-visible, marketing is NEVER recommended) |critical(a serious defect users must act on — the only tier that ever surfaces to users, #1977; use sparingly, when the fix matters more than the silence). Force-upgradeable defects go toadvisories/, never here.- The summary is model-written, ≤400 chars, newest-first order, cap 20
entries. NEVER hand-edit the companion package's own
"version"field — CI bumps it on publish. - Full rules:
release-notes/README.md. Enforcement: the gates inrelease.yml/release-manual.yml/release-bugfix.ymlpass with a notice when the entry is absent (silent release, the default) and validate it when present.
- Local pre-flight — run the same checks CI runs:
npm run typecheck npm test npm run build
5.5. Local real-model release gate (operator machines with live models —
the regression lane GitHub CI can never run). After npm run build:
npm run gate:local
# or against an already-built tarball:
node scripts/release-gate-local.mjs --tarball /path/to/billion-context-X.Y.Z.tgz
This freezes the manual v0.1.196 review pass (PR #2962) into one command.
Lanes: A compression — real dsh session at a small-window route forces
a mid-turn fold (nudge INJECT → preflight → acp-compress-obs), then the
SAME session keeps answering from folded context with cache recovered
(≥50% on a stable-prefix follow-up); B model switch — same session
resumed on a DIFFERENT model / upstream (same lineage — a dsh
resume-replay fork that ADOPTS the parent's folded blocks counts as pass,
an orphaned pfa does not —, folded state survives a proxy restart,
cross-upstream baseline demoted to untrusted, cache cold→hot); U
(--with-update, needs verdaccio + GATE_VERDACCIO_NPMRC) — the profile
proxy recognizes its dsh-managed install and reads latest from the
configured update registry. Everything is hermetic (own DSH_HOME,
BILI_CONFIG_FILE, sessions/XDG dirs, ports); it never touches ~/.dsh or
running proxies. Prerequisites are probed and missing lanes are skipped
with a warning — see the header of scripts/release-gate-local.mjs for all
GATE_* knobs. Windows-specific update lanes (global installer,
desktop-profile in-place swap, doctor) stay on the Win10 VM checklist below.
6. Commit, push, open PR — release-commit convention:
- Message:
release v{VERSION} - The commit changes ONLY
package.json(+package-lock.jsonif it drifts). Never bundle other changes into a release commit. - PR title:
release v{VERSION}; body lists changes since last tag.
- Human merges the PR (Agent MUST NOT merge).
- CI publishes automatically — no manual
npm publish:- On merge,
release.ymldetects the*_release-v*branch name +release v{VERSION}commit message. - It runs
npm ci+typecheck+test+build, thennpm publish --tag latest(using theNPM_TOKENrepo secret), creates git tagv{VERSION}, and creates a GitHub Release.
- On merge,
- Verify the published version is live:
npm view billion-context version
One-click manual release (fast path)
For routine patch releases, skip the branch/PR dance: Actions → "Release
(one-click)" → Run workflow (.github/workflows/release-manual.yml). The version
input is optional — blank means auto next-patch over the npm latest; type a full
semver for minor/major/prerelease bumps.
Severe-release prerequisite (#1870): if the version being released is
severe, its release-notes entry must ALREADY be merged to master
(release-notes/package.json, same shape as step 4 above) — the workflow
checks at dispatch time and logs the entry when found. Ordinary releases
need NO entry: a missing entry is a notice, not an abort. Prereleases (dev
channel) are exempt.
The workflow then:
- Drift guard: master's
package.jsonversion must equal the npm latest, else it aborts (never release off a drifted tree). It also rejects a target version that is already published. A separate dispatch-time step then logs the release-notes entry for the target version when present (#1870) — see the prerequisite above. - Bumps ONLY
package.json+package-lock.jsonand commitsrelease v{VERSION}— the same one-version-one-commit discipline asAGENTS.mdVersion Bumps. - Runs the full pre-flight gate (
npm ci+ typecheck + test + build). - Pushes the release commit directly to
master(GITHUB_TOKEN, fast-forward only). If branch protection blocks direct pushes, the release lands on a release branch instead and the run tries to open the release PR itself (best-effort — if the account forbids Actions-created PRs the run still finishes green with a one-click "open the release PR" link in the job summary). The fallback PR body carries a generated changelog (git logsince the last release tag); the same notes appear in the job summary as a paste-ready block for opening the PR manually. Merging that PR publishes via the standard flow; red is reserved for real failures (guard trips, gate failures, or a failed branch push). GitHub suppresses push-event delivery for ref updates made with GITHUB_TOKEN, so the push trigger never fires on the fallback branch; instead the run explicitly dispatchesci.ymlon that branch (POST …/actions/workflows/ci.yml/dispatches, ref = branch; requires theworkflow_dispatchtrigger thatci.ymldeclares for exactly this purpose). Those check runs land on the same head sha — once green, required checks pass and the auto-PR is mergeable without approving itsaction_requiredpull_request runs (bot-authored PRs are gated there) (#772, #1744). If the dispatch fails (transient API error), the fallback PR stays gated until someone approves those runs manually. (Push-triggered CI on release branches still works for branches pushed with a real account token — e.g. agent-driven standard-flow release branches.) - Publishes to npm (
latest, ordevfor prerelease), tagsv{VERSION}, and creates the GitHub Release with notes generated fromgit logsince the last tag.
A successful one-click run does NOT double-trigger release.yml: its check only
matches release-branch merges / date-prefixed commits, never a plain release v{VERSION}
commit. The standard branch/PR flow above remains the canonical path for anything
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), 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 carve-out PR's head tree instead — the artifact is exactly that tree,
nothing else.
Process:
- Cut the hotfix branch from the last released TAG (not master), apply ONLY the fix
plus the version bump (regenerate
package-lock.jsonas 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:Thegit checkout -b bugfix-release/v{VERSION}-{slug} v{LAST-RELEASED-TAG}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 whatrelease.yml's detection deliberately does NOT match, so merging the PR cannot double-publish the post-merge master through the normal channel. Guard-compatibility requirement: the ci.ymlversion-guardMUST whitelist this prefix in parallel with*_release-v*— a carve-out PR legally carries exactly one isolated release-bump commit. #2858 was exactly this divergence: #2853 updated release-bugfix.yml / AGENTS.md / this doc but not ci.yml, so every carve-out PR went red on version-guard and the fail-closed full-CI gate blocked every merge-time publish until the guard was fixed on master. - 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_requesttriggers), which the publish gate reuses. - On merge,
release-bugfix.yml(pull_requestclosed trigger) validates (merged, same-repo head,bugfix-release/*branch), checks out the PRE-MERGE PR head tree, reads the target version from itspackage.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 stableXis refused while npm latest isX-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).
- strictly newer than npm latest (base-semver compare — never holds or downgrades
- 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). - Publishes
--tag latest(devfor prereleases), pushes tagv{VERSION}, creates the GitHub Release with notes generated fromgit logbetween 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 NOTgenerate_release_notes:true, which would span into unreleased master work).
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)
- Trigger: push to
masterwhere the merge commit or branch name matches*_release-v*. - Prerelease handling: if the version contains
-(e.g.0.1.17-beta.1), publishes with--tag devinstead of--tag latest. - No publish step for the Agent: the Agent never runs
npm publish. The only manual fallback (if CI is down) is a human runningnpm publish.
Kernel releases (standalone acp-kernel artifact, #2092)
The kernel source lives in-repo under kernel/ and is consumed via
"acp-kernel": "file:./kernel", so every billion-context release bundles the in-tree
kernel — there is NO registry ordering to manage anymore (the old "acp-kernel MUST
ship first" rule is obsolete).
When accumulated kernel changes warrant a standalone npm release of acp-kernel
(downstream consumers such as the legacy billion-context-pi pick it up as usual):
- Branch
YYYY-MM-DD_release-kernel-v{VERSION}off master. - ONE commit
release kernel v{VERSION}changing ONLY the version inkernel/package.json(then regenerate the rootpackage-lock.jsonsopackages.kernel.versiontracks it — same command as step 3 above; enforced by thelock-syncguard, #2704). - Open a PR (its body serves as the release notes; no release-notes entry required). HUMAN merges.
.github/workflows/release-kernel.ymlruns on the merge: full bili gate (typecheck + test + build) plus the kernel suite against its TS source, then publishesacp-kernelfromkernel/, tagskernel-v{VERSION}, creates a GitHub Release.
Cross-trigger safety: *_release-kernel-v* and *_release-v* are mutually exclusive
in every matching direction (release.yml's merge-branch regex, direct commit messages
release v* vs release kernel v*, the version-guard job, the kernel-guard job), and
the tag namespaces never collide (v* vs kernel-v*).
Auto-update testing
To test that a running older version auto-updates to a newer registry version:
# 1. Install older version from registry
npm install -g billion-context@0.1.16
# 2. Merge the newer release PR (HUMAN merges) — CI publishes 0.1.17 to npm.
# 3. Start the older version
bili start --port 19195
# Within ~10s (startup check) it detects 0.1.17 and installs it, logging:
# ✔ billion-context auto-updated 0.1.16 → 0.1.17. Restart bili to finish.
⚠ Releasing changes to the auto-update mechanism itself
The auto-update code (src/update.ts) is load-bearing for every future upgrade. If
a release ships a broken auto-update, users who install it become permanently stuck
— they can never auto-update again (the broken thing is the updater itself), and many
will never notice to manually reinstall. This is strictly worse than a normal bug: a
normal bug affects one feature; a broken updater silently bricks the upgrade path for
everyone who hits it.
Therefore: any change to src/update.ts (the download / extract / install /
version-check logic) MUST be validated with a no-op release BEFORE shipping the change.
The sequence is:
- Ship a no-op release first (pure version bump, zero code changes) — this proves
the existing upgrade path is healthy end-to-end: the currently-installed version
auto-updates to the no-op release using the old code.
- Branch:
YYYY-MM-DD_release-v{VERSION}(same naming convention). - Commit:
release v{VERSION}(version bump only). - PR body MUST state it is a no-op and why (validation release).
- Branch:
- Only after the no-op release is confirmed on npm (
npm view billion-context versionreturns it) AND a real upgrade has been observed succeeding (the log showsauto-updated OLD → NEW), ship the actual change as a separate subsequent release. - If the no-op release's upgrade fails, STOP. Do not ship the updater change. Investigate the existing-path failure first — the existing code is the only known-good upgrade path, and shipping a change on top of an already-broken path compounds the problem.
Why the indirection? Because if the change-to-the-updater is itself buggy, anyone who upgrades to it is bricked. The no-op release isolates the test: it exercises the upgrade path using code we already trust, so a success confirms the plumbing (registry, tarball, file copy, restart) works, independent of the new code. Only then do we trust the new code to run on the next hop.
Concrete example (v0.1.22): the Windows auto-update fix (replacing
execFile("tar"/"cp") with the tar npm package + fs.cp) was staged in PR#44 but NOT
shipped directly. A no-op v0.1.22 (PR#46, version bump only) was released first to
confirm the running v0.1.21 could self-upgrade. Only after that succeeded was the
Windows fix shipped in a follow-up release.
Local real-model gate on the Win10 VM (manual checklist)
npm run gate:local covers the Linux lanes. The Windows-only update lanes are
NOT automatable from the host yet; before a release that touched
src/update.ts, src/dsh-channel.ts or the installer, run this checklist on
the Win10 VM (per the operator's VM runbook; all commands in cmd.exe):
- Baseline: pin global + the 4 dsh profiles (acp/headless/desktop/web) to the
PREVIOUS release from the local verdaccio registry;
bili --versionmust report it. - Set
"update": {"registry": "http://<verdaccio-LAN-IP>:4873"}in the VM's billion-context.json; publish the candidate tarball to verdaccio first. bili update→ expect: global bump,refreshed … dsh profile bundle(s), desktop in-place swap, and (when upgrading FROM a version that already has #2894)[update] dsh desktop profile manifest spec now declares vX.Y.Zwith the profile package.json spec converged (^old→^new).bili doctor→ 0 stale / 0 frozen lanes.- Restart the fixed 8787 instance (run-bili3.bat) and re-run the dsh compression / model-switch / cache checks (Lane A/B equivalents).