From 3d56a5375f99477dbfa42f28d1f85ec97610b879 Mon Sep 17 00:00:00 2001 From: ranxianglei Date: Sun, 25 Oct 2026 16:12:51 +0800 Subject: [PATCH 1/6] release: v3 gate-branch publish model (lane -> bugfix fires; auto-cut next lane on alignment merge) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - release-bugfix.yml: THE FIRE is now exactly one PR shape — a same-repo MERGED PR base=bugfix head=bugfix-vX.Y.Z publishing its post-merge lane head. Merging carries INTO a lane publishes nothing (kills the 'any merge into the lane ships' hazard). Second path: a merged alignment PR (head=bugfix, base=master, title contract 'align master with vX.Y.Z (shipped from )') AUTO-CUTS the next lane bugfix-vX.Y.Z from tag vX.Y.Z with package.json pre-bumped +1 patch (stage P4; idempotent; failure posts manual recovery and fails loudly). Alignment PR now heads from bugfix -> master. All version guards / full-CI dispatch+wait / fast dispatch escape hatch / legacy dormant carve-out path unchanged. - ci.yml: 'bugfix' added to push+pull_request branch lists; plan scope forces FULL matrix for base=bugfix ship PRs (born full-scope like #3688 release PRs). e2e lanes are label-gated (ci:full), so the ship PR gets that label at open time — no e2e yml changes needed. - reference/release.md: gate-branch model v3 (roles of bugfix / tag lanes / master, P0-P4 cycle, alignment title contract, protection payload incl. context-roster rule), dual-lane section aligned (auto-cut, ship PR lane->bugfix, CI wiring v3). --- .github/workflows/ci.yml | 14 +- .github/workflows/release-bugfix.yml | 365 +++++++++++++++++---------- reference/release.md | 176 ++++++++----- 3 files changed, 358 insertions(+), 197 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 4f74ef2db4..46319fc394 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -13,7 +13,7 @@ on: # lane or a bugfix-release/** carve-out get the CORE matrix directly; # backport.yml's token pushes compensate by dispatching this workflow # on the carry/lane ref. - branches: [master, "*_release-v*", "bugfix-release/**", "bugfix-v*"] + branches: [master, "*_release-v*", "bugfix-release/**", "bugfix-v*", bugfix] pull_request: # agent-relay: #3468 agent PRs target the relay branch. # bugfix-v*: carry PRs INTO the current patch lane (backport/carry-N) @@ -21,7 +21,10 @@ on: # release-bugfix.yml's dispatch, not this trigger. # bugfix-release/**: legacy one-off carve-out branches keep their old # behaviour. - branches: [master, agent-relay, "bugfix-v*", "bugfix-release/**"] + # bugfix: THE GATE branch (v3 release model). Ship PRs (tag lane -> + # bugfix) must run the FULL matrix BEFORE the merge can happen — the + # scope step below forces full for base=bugfix regardless of labels. + branches: [master, agent-relay, "bugfix-v*", "bugfix-release/**", bugfix] # three-layer CI (#3295): synchronize keeps the CORE matrix blocking on # every push; `labeled` lets the `ci:full` label widen a PR to the FULL # matrix without a re-push (other labels no-op in the plan job). @@ -119,6 +122,7 @@ jobs: # pull_request case below. PR_AUTHOR: ${{ github.event.pull_request.user.login }} PR_HEAD_REF: ${{ github.event.pull_request.head.ref }} + PR_BASE_REF: ${{ github.event.pull_request.base.ref }} PR_TITLE: ${{ github.event.pull_request.title }} HEAD_SHA: ${{ github.sha }} FULL_INPUT: ${{ inputs.full }} @@ -192,8 +196,14 @@ jobs: # lane ship PRs are deliberately NOT glob-matched: their own # workflow gates the full suite at the PR head tree already # (lane ship PRs ride the bot-author rule above). + # v3 gate-branch model: a ship PR INTO `bugfix` is born + # full-scope — that merge IS the publish decision, so the FULL + # matrix must exist at the PR head before the human merges + # (same label/merge race lesson as #3688); no ci:full label + # needed on the ship PR itself. [ "${PR_AUTHOR:-}" = "github-actions" ] \ || [ "${PR_AUTHOR:-}" = "app/github-actions" ] \ + || [ "${PR_BASE_REF:-}" = "bugfix" ] \ || case "${PR_HEAD_REF:-}" in *_release-v*) true ;; *) false ;; esac \ || case "${PR_TITLE:-}" in "[PR] release"*|"release v"[0-9]*) true ;; *) false ;; esac then diff --git a/.github/workflows/release-bugfix.yml b/.github/workflows/release-bugfix.yml index 54054302ed..439aa8eb83 100644 --- a/.github/workflows/release-bugfix.yml +++ b/.github/workflows/release-bugfix.yml @@ -1,72 +1,86 @@ -name: Bugfix Release (carve-out) +name: Bugfix Release (gate-branch model) -# Dedicated emergency / hotfix publish channel (#2011), PR-gated since #2851. +# Patch-lane release channel, v3 model (2026-10-25, owner decision; supersedes +# the v2 "any merge INTO a lane publishes" trigger and the backport-ship label +# path from #4596 — both decommissioned). # -# Publishes a version cut from a NON-master ref -- e.g. a released tag plus -# fixes -- STRICTLY excluding the unreleased work that has since 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. +# THREE BRANCHES, ONE ROLE EACH: +# bugfix THE GATE. A standalone PROTECTED branch with the same +# status as master (PR-only, required checks, no +# force/delete). It never accumulates development; it only +# RECEIVES a finished tag lane. +# bugfix-vX.Y.Z THE TAG LANES. Each cycle's lane is cut from the released +# vX.Y.Z tag (first lane manually; every later lane +# AUTO-CUT by this workflow, stage P4 below) and carries +# package.json pre-bumped to the next version. All fixes +# enter a lane through reviewed carry PRs (backport.yml +# auto-opens them from the `backport` label); those +# merges NEVER publish. +# master MAINLINE. Re-aligned after every publish via the +# auto-opened alignment PR (stage P3). # -# MERGE-GATED LANE PUBLISH (v2 model, 2026-10-25; SUPERSEDES the backport-ship -# label path from #4596 -- a label publishes without a human merge decision -# and is deliberately gone now): -# - A patch lane (bugfix-v*) is cut from the latest released TAG and is a -# PROTECTED branch with the same status as master (PR-only, required -# checks, no force/delete). Every piece of content enters the lane -# through a reviewed PR -- there is no other way. -# - When such a PR MERGES into the lane, THIS workflow fires (the -# `pull_request_target` closed trigger below; GitHub runs the lane-side -# copy of this file against the base ref) and publishes the POST-MERGE -# LANE HEAD (= the merge sha) -- exactly the reviewed state of the lane, -# nothing else. The human MERGE BUTTON IS THE RELEASE TRIGGER: no label, -# no direct push, no silent auto-publish. -# - Right after a successful publish the workflow AUTO-OPENS an alignment -# PR (lane -> master) so master picks up the shipped content. It -# structurally conflicts (master evolved past the older tag); resolve -# master-first, keeping only lane-unique content. Merging it closes the -# release cycle. -# - The target version lives in the LANE's package.json (bumped when the -# lane was cut), so the guards below enforce monotonicity without any -# further input. -# - Emergency escape hatch: manual workflow_dispatch with the `fast` input -# (owner-owned risk; skips the full-CI lanes + the full npm test, keeps -# every version guard + npm ci + typecheck + build). +# THE FIRE IS ONE EXACT PR SHAPE AND NOTHING ELSE: +# a SAME-REPO PR, MERGED, base = `bugfix`, head = `bugfix-vX.Y.Z`. +# That merge publishes the POST-MERGE lane head (= the merge sha) through +# the full guard chain. Every other close — any PR into a lane, any +# non-tag-branch into `bugfix`, a non-merged close, a fork — is a +# millisecond no-op. Merging carries into a lane therefore NEVER ships a +# version; only the explicit lane -> bugfix ship PR does. # -# LEGACY path (kept dormant): the original `pull_request` closed trigger for -# bugfix-release/* one-off carve-outs PR'd AGAINST MASTER predates the lane -# model. It still works so an old in-flight carve-out can finish safely; new -# work must go through a protected lane. +# CYCLE (v3): +# P1 carry PRs (reviewed, full checks) land in bugfix-vX.Y.Z [silent] +# P2 ship PR bugfix-vX.Y.Z -> bugfix is MERGED [PUBLISH: +# post-merge lane head -> version guards -> full CI dispatch+wait +# at the publish sha -> npm/typecheck/test/build -> tag -> npm +# publish -> GH Release; audit comment left on the ship PR] +# P3 right after a successful publish this workflow AUTO-OPENS the +# alignment PR (head=`bugfix` -> master; title contract below). The owner +# merges it (structural conflicts expected; master-first resolution). +# P4 the merge of THAT alignment PR fires this workflow again (second path +# below): it AUTO-CUTS the next lane bugfix-vX.Y.Z from tag vX.Y.Z +# (pre-bumped +1 patch) so the following cycle starts with zero manual +# steps. Only the very first lane (bugfix-v0.1.206) was cut manually. # -# 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 LANE HEAD tree itself -- the artifact is -# exactly that tree, nothing else. +# ALIGNMENT PR TITLE CONTRACT (load-bearing for P4): +# "align master with vX.Y.Z (shipped from )" +# Renaming this format silently breaks the auto-cut; documented in +# reference/release.md. +# +# Emergency escape hatch: workflow_dispatch with `fast=true` (owner picks the +# ref in the UI): skips the full-CI dispatch/gate and the full npm test, keeps +# every version guard + npm ci + typecheck + build. Owner-owned risk. +# +# LEGACY path (kept dormant, unchanged): the original `pull_request` closed +# trigger for bugfix-release/* one-off carve-outs PR'd AGAINST MASTER predates +# the lane model. It still works so an old in-flight carve-out can finish +# safely; new work must go through the gate-branch flow. # # Guarded so it can never: -# - move `latest` backwards (target must be strictly newer than npm latest); +# - move `latest` backwards (target strictly newer than npm latest); # - re-publish an already-live version; # - ship a sub-0.1.0 line (#1385); -# - act on fork PRs (secrets unavailable) or on non-merged closes; -# - publish anything but the reviewed post-merge lane head. +# - act on fork PRs (secrets unavailable) or non-merged closes; +# - publish anything but the reviewed post-merge lane head; +# - fire on ANY other merge shape (see THE FIRE above). # -# Master interaction: the post-publish alignment PR brings the lane content -# (and the version bump) INTO master. Master's next normal release MUST be -# higher than the carved-out version -- the one-click bump derives from npm -# latest, so this holds automatically. +# Master interaction: the post-publish alignment PR brings the shipped lane +# content (and the version bump) INTO master. Master's next normal release +# MUST be higher than the shipped version -- the one-click bump derives from +# npm latest, so this holds automatically. on: pull_request: types: [closed] branches: [master] pull_request_target: - # v2 merge-gated lane publish: fires when a PR is CLOSED against a patch - # lane; the resolve step no-ops within milliseconds on every close that - # is not a MERGE into a bugfix-v* / bugfix-release/** lane. Runs the - # BASE (lane-side) copy of this workflow with secrets; the resolve step - # rejects fork PRs before any head content is touched. + # v3 dual path (resolve step sorts it out): + # A) base=`bugfix`, head=`bugfix-vX.Y.Z`, merged => PUBLISH + # B) base=`master`, head=`bugfix`, merged, alignment title => AUTO-CUT + # Runs the BASE-side copy of this workflow with secrets; the resolve step + # rejects fork PRs before any head content is touched and no-ops within + # milliseconds on every close that is not one of the two shapes. types: [closed] - branches: ["bugfix-v*", "bugfix-release/**"] + branches: [bugfix, master] workflow_dispatch: inputs: fast: @@ -85,26 +99,30 @@ jobs: contents: write id-token: write actions: write - pull-requests: write # annotate the merged lane PR + auto-open the alignment PR + pull-requests: write # annotate the ship PR + auto-open the alignment PR + announce auto-cuts steps: - - name: Validate trigger + resolve the publish ref + - name: Validate trigger + resolve the path (publish | cut | noop) id: resolve run: | + PATH=noop + BRANCH="" + SHA="" + VER="" + TITLE="$(jq -r '.pull_request.title // ""' "$GITHUB_EVENT_PATH")" if [ "$GITHUB_EVENT_NAME" = "pull_request" ]; then # LEGACY one-off carve-out: PR against master whose head is the # carve-out branch. Publishes the PRE-MERGE head on merge. MERGED="$(jq -r '.pull_request.merged' "$GITHUB_EVENT_PATH")" - BRANCH="$(jq -r '.pull_request.head.ref' "$GITHUB_EVENT_PATH")" + HEADREF="$(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 + case "$HEADREF" in bugfix-release/*) ;; # legacy one-off carve-out *) - echo "::notice::head branch '$BRANCH' is not a legacy bugfix-release/* carve-out — nothing to publish" + echo "::notice::head branch '$HEADREF' is not a legacy bugfix-release/* carve-out — nothing to publish" exit 0 ;; esac @@ -112,71 +130,150 @@ jobs: echo "::error::fork PRs cannot use the carve-out channel (repo secrets are unavailable for them)" exit 1 fi + PATH=publish + BRANCH="$HEADREF" + SHA="$(jq -r '.pull_request.head.sha' "$GITHUB_EVENT_PATH")" elif [ "$GITHUB_EVENT_NAME" = "pull_request_target" ]; then - # v2 merge-gated lane publish: a REVIEWED PR was merged into a - # patch lane. Publish the POST-MERGE lane head (== merge sha). MERGED="$(jq -r '.pull_request.merged' "$GITHUB_EVENT_PATH")" STATE="$(jq -r '.pull_request.state' "$GITHUB_EVENT_PATH")" - BRANCH="$(jq -r '.pull_request.base.ref' "$GITHUB_EVENT_PATH")" - SHA="$(jq -r '.pull_request.merge_commit_sha' "$GITHUB_EVENT_PATH")" + BASE="$(jq -r '.pull_request.base.ref' "$GITHUB_EVENT_PATH")" + HEADREF="$(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")" if [ "$STATE" != "closed" ] || [ "$MERGED" != "true" ]; then - echo "::notice::PR $GITHUB_EVENT_NUMBER is '$STATE' (merged=$MERGED) — only MERGES into a lane publish" + echo "::notice::PR $GITHUB_EVENT_NUMBER is '$STATE' (merged=$MERGED) — only MERGED same-repo PRs act" exit 0 fi - case "$BRANCH" in - bugfix-v*) ;; # protected patch lane (v2 model) - bugfix-release/*) ;; # same treatment for lane-shaped targets - *) - echo "::notice::base branch '$BRANCH' is not a patch lane — nothing to publish" - exit 0 - ;; - esac - if [ "$SAME_REPO" != "true" ]; then - echo "::error::fork PRs cannot use the lane publish channel (repo secrets are unavailable for them)" - exit 1 + # ---- path A: the ship shape — a TAG LANE merged into `bugfix` ---- + if [ "$BASE" = "bugfix" ]; then + case "$HEADREF" in + bugfix-v[0-9]*.[0-9]*.[0-9]*) ;; + *) + echo "::notice::'$HEADREF' -> bugfix is not a tag lane (bugfix-vX.Y.Z) — NOT a ship PR; nothing to publish" + exit 0 + ;; + esac + if [ "$SAME_REPO" != "true" ]; then + echo "::error::fork PRs cannot use the gate-branch publish channel (repo secrets are unavailable for them)" + exit 1 + fi + PATH=publish + BRANCH="$HEADREF" + SHA="$(jq -r '.pull_request.merge_commit_sha' "$GITHUB_EVENT_PATH")" + echo "::notice::SHIP PR detected: $HEADREF -> bugfix @ ${SHA:0:12} — publishing the post-merge lane head" + # ---- path B: the alignment landed — auto-cut the next lane ---- + elif [ "$BASE" = "master" ] && [ "$HEADREF" = "bugfix" ]; then + if [ "$SAME_REPO" != "true" ]; then + echo "::error::fork PRs cannot drive the auto-cut (repo secrets are unavailable for them)" + exit 1 + fi + case "$TITLE" in + "align master with v"*) + REST="${TITLE#align master with v}" + VER="${REST%% *}" + if ! printf '%s' "$VER" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$'; then + echo "::error::alignment title does not follow the contract 'align master with vX.Y.Z (...)' (parsed version '$VER') — auto-cut refused" + exit 1 + fi + PATH=cut + echo "::notice::alignment PR '$TITLE' merged — auto-cutting lane bugfix-v$VER from tag v$VER" + ;; + *) + echo "::notice::bugfix -> master merge without the alignment title contract ('$TITLE') — nothing to cut" + exit 0 + ;; + esac + else + echo "::notice::base '$BASE' / head '$HEADREF' matches neither ship nor alignment shape — nothing to do" + exit 0 fi else + # workflow_dispatch: EMERGENCY fast publish of the selected ref + PATH=publish BRANCH="$GITHUB_REF_NAME" SHA="" fi + [ "$PATH" = "noop" ] && { echo "proceed=false" >> "$GITHUB_OUTPUT"; exit 0; } + echo "proceed=true" >> "$GITHUB_OUTPUT" + echo "path=$PATH" >> "$GITHUB_OUTPUT" echo "branch=$BRANCH" >> "$GITHUB_OUTPUT" echo "sha=$SHA" >> "$GITHUB_OUTPUT" - echo "proceed=true" >> "$GITHUB_OUTPUT" + echo "ver=$VER" >> "$GITHUB_OUTPUT" - - name: Checkout + - uses: actions/checkout@v4 if: steps.resolve.outputs.proceed == 'true' - uses: actions/checkout@v4 with: fetch-depth: 0 + - name: Auto-cut the next tag lane (path B — after the alignment merge) + # v3 stage P4: the alignment PR (bugfix -> master) just merged. Cut + # bugfix-vX.Y.Z from tag vX.Y.Z, pre-bump package.json to the next + # patch version, push. Idempotent: an existing branch is a no-op. + # NOTE: GITHUB_TOKEN cannot apply branch protection — the announcement + # comment tells the owner the one remaining manual click (Settings -> + # Branches, or the PUT JSON in reference/release.md). + if: steps.resolve.outputs.path == 'cut' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + set -uo pipefail + VER="${{ steps.resolve.outputs.ver }}" + NEW_LANE="bugfix-v$VER" + MANUAL_CMDS='git fetch origin tag v'"$VER"' --no-tags && git checkout -b '"$NEW_LANE"' v'"$VER" && (edit package.json version to the next patch) && git commit -am "release: cut $NEW_LANE from v$VER" && git push origin '"$NEW_LANE" + fail() { + echo "::error::$1" + gh pr comment "$GITHUB_EVENT_NUMBER" --body "❌ **Auto-cut failed**: $1\n\nManual recovery:\n\`\`\`bash\n$MANUAL_CMDS\n\`\`\`\nThen protect \`$NEW_LANE\` exactly like master (reference/release.md § Lane protection)." \ + || echo "::warning::could not annotate PR $GITHUB_EVENT_NUMBER" + exit 1 + } + git fetch origin "refs/tags/v$VER" --no-tags || fail "tag v$VER not found on origin — the alignment was merged before the publish tag existed?" + git rev-parse --verify --quiet "v$VER^{commit}" >/dev/null || fail "tag v$VER present but unresolvable" + LIVE="$(git ls-remote origin "refs/heads/$NEW_LANE" | awk '{print $1}')" + if [ -n "$LIVE" ]; then + echo "::notice::$NEW_LANE already exists on origin ($LIVE) — idempotent no-op" + exit 0 + fi + NEXT="$(node -p "(function(){const v=process.argv[1].split('.');return v[0]+'.'+v[1]+'.'+(Number(v[2])+1)})" "$VER")" + git checkout -b "$NEW_LANE" "v$VER" + sed -i "s/\"version\": \"$VER\"/\"version\": \"$NEXT\"/" package.json + node -e "if(require('./package.json').version!=='$NEXT'){console.error('::error::pre-bump failed');process.exit(1)}" + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + git commit -q -m "release: auto-cut patch lane $NEW_LANE from v$VER; pre-bump package.json to $NEXT (v3 stage P4)" + git push -q origin "$NEW_LANE" || fail "push of $NEW_LANE rejected" + SHA="$(git rev-parse HEAD)" + gh pr comment "$GITHUB_EVENT_NUMBER" --body "✅ **Stage P4 complete** — lane \`$NEW_LANE\` auto-cut from tag \`v$VER\` (@ ${SHA:0:12}), package.json pre-bumped to \`$NEXT\`. One manual step remains before it takes on carries: apply the same protection as master (Settings → Branches → \`$NEW_LANE\`; payload: reference/release.md § Lane protection). Carry PRs (backport label) can start immediately." \ + || echo "::warning::could not annotate PR $GITHUB_EVENT_NUMBER (non-fatal)" + echo "::notice::lane cycle advanced: next lane $NEW_lane ready (unprotected until the owner clicks)" + - name: Switch to the publish tree (post-merge lane head / legacy pre-merge head) - # v2: publish the EXACT reviewed state — the merge sha of the PR that - # just landed in the lane. Legacy: pre-merge head of a merged - # carve-out PR. If the lane head has already moved past the merge sha - # (another PR landed first while this run queued behind it under the - # concurrency group), warn loudly and still publish the reviewed sha; - # the newer content rides the next release. - if: steps.resolve.outputs.proceed == 'true' && (github.event_name == 'pull_request' || github.event_name == 'pull_request_target') + # v3 path A: publish the EXACT reviewed state — the merge sha of the + # ship PR that just landed in `bugfix`. Legacy: pre-merge head of a + # merged carve-out PR. If the LANE head has moved past the merge sha + # (another carry landed while this run queued behind the ship PR under + # the concurrency group), warn loudly and still publish the reviewed + # sha; content past a SHIPPED lane never rides another release of that + # lane (the monotonic guard freezes it) — move it forward to master + # and carry it into the NEXT lane. + if: steps.resolve.outputs.path == 'publish' && steps.resolve.outputs.sha != '' run: | SHA="${{ steps.resolve.outputs.sha }}" BRANCH="${{ steps.resolve.outputs.branch }}" git rev-parse --verify --quiet "${SHA}^{commit}" >/dev/null || git fetch origin "$SHA" LIVE_HEAD="$(git ls-remote origin "refs/heads/$BRANCH" | awk '{print $1}')" if [ -n "$LIVE_HEAD" ] && [ "$LIVE_HEAD" != "$(git rev-parse ${SHA}^{commit})" ]; then - echo "::warning::lane '$BRANCH' head ($LIVE_HEAD) differs from the merge sha ($SHA) — publishing the reviewed merge sha anyway; newer lane content will ride the NEXT release" + echo "::warning::lane '$BRANCH' head ($LIVE_HEAD) is past the ship merge sha ($SHA) — publishing the reviewed merge sha only; anything newer on the lane is FROZEN out of this lane's releases (monotonic guard) and must ride master/the next lane" fi git checkout --detach "$SHA" - uses: actions/setup-node@v4 - if: steps.resolve.outputs.proceed == 'true' + if: steps.resolve.outputs.path == 'publish' with: node-version: 22 registry-url: https://registry.npmjs.org - name: Read version id: version - if: steps.resolve.outputs.proceed == 'true' + if: steps.resolve.outputs.path == 'publish' run: | V="$(node -p "require('./package.json').version")" case "$V" in @@ -189,7 +286,7 @@ jobs: 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)" + echo "::notice::Publishing from lane '$REF' @ ${SHA:0:12} -> v$V (master NOT involved)" - name: Check plugin manifest versions (#4449) # Same gate as release.yml: the publish tree is a frozen lane state @@ -197,7 +294,7 @@ jobs: # synced plugin manifests — drift fails fast here instead of shipping # a release whose marketplace update detection never fires. See # reference/release.md. - if: steps.resolve.outputs.proceed == 'true' + if: steps.resolve.outputs.path == 'publish' # #4576 follow-up: lanes cut from a pre-#4449 tag do not carry the # manifest sync script at all -- fail-open with a notice there instead # of MODULE_NOT_FOUND (same existence-guard philosophy as release-manual's @@ -210,7 +307,7 @@ jobs: fi - name: Publish guard (monotonic + not-already-live) - if: steps.resolve.outputs.proceed == 'true' + if: steps.resolve.outputs.path == 'publish' run: | VER="${{ steps.version.outputs.version }}" LATEST="$(npm view billion-context version)" @@ -235,7 +332,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' + if: steps.resolve.outputs.path == 'publish' run: | VER="${{ steps.version.outputs.version }}" case "$VER" in @@ -254,14 +351,15 @@ 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. For a v2 lane publish the merge sha is brand-new (PR-era - # lane runs sit on earlier shas), so the gate dispatches the missing - # lanes here; idempotent where runs already exist. + # npm publish. The ship PR's own runs sit on the pre-merge head; the + # merge sha is brand-new, so the gate dispatches the missing lanes + # here; idempotent where runs already exist. Belt-and-braces on top of + # the gate branch's required checks. # EMERGENCY fast mode (owner 2026-10-17): dispatch is already a # human-picked ref; with fast=true the human explicitly owns skipping # this lane matrix — version guards and the build sanity below still # run. - if: steps.resolve.outputs.proceed == 'true' && inputs.fast != true + if: steps.resolve.outputs.path == 'publish' && inputs.fast != true env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | @@ -273,7 +371,7 @@ jobs: - name: Pre-flight gate (full suite) # keep the claude-native live e2e subtests in this pre-publish gate (#1248) - if: steps.resolve.outputs.proceed == 'true' && inputs.fast != true + if: steps.resolve.outputs.path == 'publish' && inputs.fast != true env: ACP_TEST_CLAUDE_NATIVE: "1" run: | @@ -286,7 +384,7 @@ jobs: # EMERGENCY fast mode: keep the cheap sanity (install/typecheck/build) # so a broken tree still fails loudly, but skip the full npm test — # the lane matrix above was skipped by explicit human choice. - if: steps.resolve.outputs.proceed == 'true' && inputs.fast == true + if: steps.resolve.outputs.path == 'publish' && inputs.fast == true run: | echo "::warning::FAST MODE — full CI lanes and the full npm test were SKIPPED by an explicit human choice (workflow_dispatch fast=true). Publish sanity = version guards + npm ci + typecheck + build only." npm ci @@ -294,11 +392,11 @@ jobs: npm run build - name: Full CI gate (all lanes green at this sha) - # Hard precondition for publish: lanes dispatched above (plus any PR-era - # lane runs already at this 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' && inputs.fast != true + # Hard precondition for publish: lanes dispatched above (plus any runs + # already at this 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.path == 'publish' && inputs.fast != true env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} CI_GATE_TIMEOUT_MIN: "60" @@ -311,7 +409,7 @@ jobs: - name: Check if prerelease id: pre - if: steps.resolve.outputs.proceed == 'true' + if: steps.resolve.outputs.path == 'publish' run: | if echo "${{ steps.version.outputs.version }}" | grep -q '-'; then echo "tag=dev" >> $GITHUB_OUTPUT @@ -322,7 +420,7 @@ jobs: fi - name: Create tag - if: steps.resolve.outputs.proceed == 'true' + if: steps.resolve.outputs.path == 'publish' run: | git config user.name "github-actions[bot]" git config user.email "github-actions[bot]@users.noreply.github.com" @@ -330,23 +428,23 @@ jobs: git push origin "v${{ steps.version.outputs.version }}" || true - name: Publish - if: steps.resolve.outputs.proceed == 'true' + if: steps.resolve.outputs.path == 'publish' run: npm publish --tag ${{ steps.pre.outputs.tag }} --access public env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} - - name: Annotate the merged lane PR (audit trail) - # Merge-gated lane publish: the carrying PR is already merged; leave - # the audit trail on it so a later reader sees publish == that merge. - if: github.event_name == 'pull_request_target' && steps.resolve.outputs.proceed == 'true' + - name: Annotate the merged ship PR (audit trail) + # Merge-gated publish: the ship PR is already merged; leave the audit + # trail on it so a later reader sees publish == that merge. + if: steps.resolve.outputs.path == 'publish' && github.event_name == 'pull_request_target' env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | - gh pr comment "$GITHUB_EVENT_NUMBER" --body "Published v${{ steps.version.outputs.version }} from the POST-MERGE lane head \`${{ steps.resolve.outputs.sha }}\` (merge-gated lane publish, v2 flow). Master alignment follows via the auto-opened PR." \ + gh pr comment "$GITHUB_EVENT_NUMBER" --body "Published v${{ steps.version.outputs.version }} from the POST-MERGE lane head \`${{ steps.resolve.outputs.sha }}\` (gate-branch publish, v3 flow: ${{ steps.resolve.outputs.branch }} → bugfix). Master alignment follows via the auto-opened \`bugfix → master\` PR." \ || echo "::notice::could not annotate PR $GITHUB_EVENT_NUMBER (non-fatal)" - name: Create GitHub Release - if: steps.resolve.outputs.proceed == 'true' + if: steps.resolve.outputs.path == 'publish' env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | @@ -377,41 +475,40 @@ jobs: 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 "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" - - name: Open the alignment PR into master (cycle stage 5) - # v2 flow: right after a successful lane publish, open a dedicated - # alignment PR (lane -> master) so master picks up the shipped content - # (incl. the version bump). Structural conflicts vs master are EXPECTED - # (the lane is based on an older tag while master moved on): resolve - # master-first, keeping only lane-unique content. Merging this PR - # completes the release cycle. Non-fatal: a failed open is flagged and - # the PR can be opened manually. - if: github.event_name == 'pull_request_target' && steps.resolve.outputs.proceed == 'true' + - name: Open the alignment PR (bugfix -> master, cycle stage P3) + # v3: right after a successful publish, open the dedicated alignment + # PR carrying the shipped lane content (incl. the version bump) into + # master. head=`bugfix` (which now contains exactly the merged lane), + # base=master. Title contract (DO NOT RENAME — stage P4 matches it): + # "align master with vX.Y.Z (shipped from )" + # Structural conflicts vs master are EXPECTED (the lane derives from an + # older tag while master moved on): resolve master-first, keeping only + # lane-unique content. Merging this PR fires stage P4 (auto-cut of the + # next lane). Non-fatal: a failed open is flagged and can be retried + # manually. + if: steps.resolve.outputs.path == 'publish' && github.event_name == 'pull_request_target' env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | LANE="${{ steps.resolve.outputs.branch }}" VER="${{ steps.version.outputs.version }}" - OPEN_PRS="$(gh pr list --base master --head "$LANE" --state open --json number 2>/dev/null | jq 'length')" + OPEN_PRS="$(gh pr list --base master --head bugfix --state open --json number 2>/dev/null | jq 'length')" if [ "${OPEN_PRS:-0}" -gt 0 ]; then - echo "::notice::an alignment PR ($LANE -> master) is already open — leaving it as-is" + echo "::notice::an alignment PR (bugfix -> master) is already open — leaving it as-is" else - gh pr create --base master --head "$LANE" \ + gh pr create --base master --head bugfix \ --title "align master with v$VER (shipped from $LANE)" \ - --body "Auto-opened by Bugfix Release right after v$VER shipped from \`$LANE\` (post-merge sha \`${{ steps.resolve.outputs.sha }}\`). Structural conflicts vs master are EXPECTED — the lane is based on an older tag while master moved on; resolve master-first, keeping only lane-unique content (release notes, advisories, diagnostics). Merging this PR completes the release cycle." \ - || echo "::warning::could not open the alignment PR automatically — open it manually: base=master head=$LANE (non-fatal)" + --body "Auto-opened by Bugfix Release right after v$VER shipped (\`$LANE\` → bugfix, post-merge sha \`${{ steps.resolve.outputs.sha }}\`). Structural conflicts vs master are EXPECTED — the lane derives from an older tag while master moved on; resolve master-first, keeping only lane-unique content (advisories, diagnostics, fixes). Merging this PR completes the release cycle and AUTO-CUTS the next lane (bugfix-v$VER) from tag v$VER (stage P4)." \ + || echo "::warning::could not open the alignment PR automatically — open it manually: base=master head=bugfix, title MUST start with 'align master with v$VER (shipped from $LANE)' (non-fatal)" fi - - name: Close the patch-lane cycle (notice — the state is derived, nothing to clear) - # Lanes derive from the latest released tag: once this publish creates - # vNEXT, the NEXT lane is cut FRESH from vNEXT (one-click / manual - # cut). Nothing is stored, nothing to reset; the old lane stays frozen - # as the record of what shipped. - if: steps.resolve.outputs.proceed == 'true' + - name: Close the ship PR cycle (notice — the state is derived, nothing to clear) + if: steps.resolve.outputs.path == 'publish' run: | - BRANCH="${{ steps.resolve.outputs.branch }}" - echo "::notice::shipped '$BRANCH' — the fresh tag closes this lane cycle by derivation; the next lane is cut from it (aligned back to master via the auto-opened PR)" + LANE="${{ steps.resolve.outputs.branch }}" + echo "::notice::shipped '$LANE' — the fresh tag v$VER freezes this lane (the monotonic guard refuses to re-publish it); the next lane is auto-cut from the tag once master is aligned" diff --git a/reference/release.md b/reference/release.md index 5a417a4744..737a1cf9da 100644 --- a/reference/release.md +++ b/reference/release.md @@ -205,34 +205,64 @@ 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 patch-lane channel (release-bugfix.yml) +## Bugfix patch-lane channel (release-bugfix.yml — gate-branch model) Emergency hotfix path (#2011, first used for v0.1.182), PR-gated since #2851, -and since 2026-10-25 hard-gated on human review as the **protected patch-lane -model**: publish a version cut from a **non-master ref** — a released tag plus -the fixes that landed on its lane — STRICTLY excluding the unreleased work that +and since 2026-10-25 hard-gated on human review as the **protected +gate-branch model (v3)**: publish a version cut from a **non-master ref** — a +released tag plus the fixes that landed on its lane — STRICTLY excluding the +unreleased work that has since accumulated on master. -**The governing rules (v2 — supersedes the `backport-ship` label path):** - -- A patch lane (`bugfix-v*`) is a **PROTECTED branch with the same status as - master**: pull-request-only, required checks green, force-push and delete - disabled, admins included. There is NO direct-push path into a lane. -- Every piece of content enters the lane through a **reviewed PR**. -- **Merging a PR INTO the lane IS the release.** On such a merge, the - `pull_request_target` closed trigger fires and CI publishes the POST-MERGE - lane head (= the PR's `merge_commit_sha`, cross-checked against the live lane - ref with a drift warning) with the full guard chain below — then AUTO-OPENS - an alignment PR (lane → master) so master picks up the shipped content. - Merging that alignment PR completes the cycle; the next lane is cut fresh - from the new tag. Non-merged closes no-op within milliseconds; fork PRs are - rejected before any head content is touched. - -GitHub executes the WORKFLOW FILE FROM THE BASE (LANE-SIDE) COPY for -`pull_request_target` events, so the updated `release-bugfix.yml` must sit ON -the lane before its first merge-trigger can fire — it rides in with an ordinary -carry PR ("armed, not fired": until it lands, earlier merges stay silent -because the older copy simply has no such trigger). +**The governing rules (v3, 2026-10-25 — supersedes the v2 "any merge into the +lane publishes" trigger AND the `backport-ship` label path):** + +Three branches, one role each: + +- **`bugfix` — THE GATE.** A standalone PROTECTED branch with the same status + as master (PR-only, required checks green, force-push/delete disabled, + admins included). It never accumulates development; it only receives a + finished tag lane. The v3 workflow file sits ON this branch from birth + (`pull_request_target` executes the base-side copy), so there is NO + "arming" window: the first ship PR works immediately. +- **`bugfix-vX.Y.Z` — the TAG LANES.** Each cycle's lane is cut from the + released `vX.Y.Z` tag with package.json pre-bumped to the next version, and + protected exactly like master. All fixes enter through reviewed carry PRs + (opened automatically from the `backport` label); **merging carries into a + lane NEVER publishes**. +- **master** — the mainline; re-aligned after every publish (below). + +**THE FIRE IS ONE EXACT PR SHAPE AND NOTHING ELSE:** a same-repo PR, MERGED, +base = `bugfix`, head = `bugfix-vX.Y.Z`. Only that merge publishes: +`release-bugfix.yml`'s `pull_request_target` closed trigger (executing the +`bugfix`-side copy) resolves the POST-MERGE lane head (= the ship PR's +`merge_commit_sha`, cross-checked against the live lane ref with a drift +warning), runs the full guard chain below, tags + publishes + creates the +GitHub Release, leaves an audit comment on the merged ship PR, then AUTO-OPENS +the alignment PR (**head = `bugfix`**, base = master). Every other close — any +PR into a lane, any non-tag-branch into `bugfix`, a non-merged close, a fork — +is a millisecond no-op. + +Ship PRs run the COMPLETE suite: ci.yml forces FULL scope for base=`bugfix` +(no label needed), and the e2e lanes ride the standard `ci:full` label on the +ship PR. Belt-and-braces, the publish pipeline ALSO dispatches whatever is +missing of the full set at the exact post-merge sha and waits for green before +npm publish (hard fail; fast-mode skip = owner-owned risk). + +**Cycle stages:** P1 carries land in the lane (silent) → P2 the ship PR +(lane → `bugfix`) merges = publish → P3 right after success the alignment PR +(`bugfix` → master) is auto-opened; the owner merges it (structural conflicts +EXPECTED — resolve master-first, keeping only lane-unique content) → **P4 the +merge of THAT alignment PR auto-cuts the next lane**: `release-bugfix.yml`'s +second path cuts `bugfix-vX.Y.Z` from tag `vX.Y.Z`, pre-bumps package.json +(+1 patch) and pushes it — zero manual steps per cycle after the very first +(one-time manual cut: `bugfix-v0.1.206`). GITHUB_TOKEN cannot apply branch +protection, so each auto-cut ends with an announcement comment carrying the +one remaining click (Settings → Branches, or the payload below). + +**Alignment PR title contract (load-bearing for P4 — do not rename):** +`align master with vX.Y.Z (shipped from )`. An alignment PR whose title +lacks this prefix is ignored by the auto-cut path. `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 @@ -292,14 +322,33 @@ removed from `release-bugfix.yml` and from the repository vocabulary: a publish action must be a human MERGE into the protected lane. Runs labeled before the removal complete on their own terms; do not apply the label again. -**Master interaction:** after a lane publish the pipeline AUTO-OPENS the -alignment PR (lane → master) carrying the shipped content incl. the version -bump; structural conflicts vs an evolved master are EXPECTED — resolve -master-first, keeping only lane-unique content. Merging it completes the cycle -(master then equals npm latest, so the master lane's drift guard sees a clean -tree again). Master's next normal release MUST be higher than the shipped -version (after v0.1.206 shipped off its lane, the next normal release is ≥ -0.1.207). +**Lane / gate-branch protection (same status as master — the one manual +click per new branch):** Settings → Branches → Add rule (or API — GITHUB_TOKEN +cannot): +```json +PUT /repos//billion-context/branches/{bugfix | bugfix-vX.Y.Z}/protection +{ + "required_status_checks": { "strict": true, "contexts": [""], "context_options": [] }, + "enforce_admins": false, + "required_pull_request_reviews": { "required_approving_review_count": 0 }, + "allow_force_pushes": { "enabled": false }, + "allow_deletions": { "enabled": false } +} +``` +Context rosters come from the PR's own commits/check-runs (a required context +that ever lands `skipped` deadlocks merges — verified on #4577: lane PRs +produce only `gate`; ship PRs into `bugfix` produce the full ci.yml names plus +the e2e lanes once labeled `ci:full`). + +**Master interaction:** after a publish the pipeline AUTO-OPENS the alignment +PR (`bugfix` → master — the gate branch contains exactly the merged lane) +carrying the shipped content incl. the version bump; structural conflicts vs +an evolved master are EXPECTED — resolve master-first, keeping only +lane-unique content. Merging it completes the cycle (master then equals npm +latest, so the master lane's drift guard sees a clean tree again) and triggers +stage P4 (auto-cut of the next lane). Master's next normal release MUST be +higher than the shipped version (after v0.1.207 ships off its lane, the next +normal release is ≥ 0.1.208). ## Dual-lane releases: label → carry PR → ship @@ -318,10 +367,11 @@ patch, 0.1.207 feature, 0.1.208 patch … all legal). The lane name IS its base tag — no stored pointer anywhere: GITHUB_TOKEN cannot touch the actions- variables API (the earlier variable-based bot 403'd on its maiden run), so the current lane is always DERIVED as `bugfix-v$(git tag --list 'v[0-9]*' --sort=-v:refname | head -1)`. -Since 2026-10-25 the lane is additionally PROTECTED with the same status as -master (see the patch-lane channel rules above) — cutting a fresh lane is a -manual step (push the branch), immediately followed by applying that -protection. +Since 2026-10-25 every lane is PROTECTED with the same status as master (see +the gate-branch rules above). Lane cutting: the FIRST lane of the epoch is +cut manually (push + protect); every later lane is AUTO-CUT by +release-bugfix.yml stage P4 (from the freshly shipped tag, pre-bumped), +leaving only the protection click for the owner. **Routing a fix (label BEFORE merge):** apply the `backport` label to the fix's OPEN PR — any base, any state. `backport.yml` reacts at once: @@ -355,16 +405,18 @@ on `merge^1..merge^2` semantics and must refuse squash/rebase merges outright (rewritten SHAs would ship a PARTIAL fix silently). Pick-from-head works for every merge shape, every time, and lets temporary fixes stay lane-only. -**Ship the lane (v2, 2026-10-25 — MERGE-GATED):** the lane is protected -exactly like master, so the ONLY way content reaches it is a reviewed PR. -**Merging the final carry PR INTO the lane IS the release**: `release-bugfix.yml`'s -`pull_request_target` closed trigger (executing the lane-side copy of the -workflow) publishes the POST-MERGE lane head (= that PR's `merge_commit_sha`), -runs the full guard chain, tags + publishes + creates the GitHub Release, -leaves the audit comment on the merged PR, and AUTO-OPENS the alignment PR -into master. Merging the alignment PR closes the cycle; the next lane is cut -fresh from the new tag. No labels, no direct pushes, no closeout step — -nothing is stored. +**Ship the lane (v3, 2026-10-25 — GATE-BRANCH):** the lane is protected +exactly like master, so the ONLY way content reaches it is a reviewed PR — and +carries merging into the lane publish NOTHING. When the batch is ready, open +the ship PR **`bugfix-vX.Y.Z` → `bugfix`** (tag it `ci:full` for the e2e +lanes; ci.yml already forces the FULL core matrix for base=`bugfix`). +**Merging THAT PR IS the release**: `release-bugfix.yml` (executing the +`bugfix`-side copy) publishes the POST-MERGE lane head (= the ship PR's +`merge_commit_sha`), runs the full guard chain, tags + publishes + creates the +GitHub Release, leaves the audit comment on the merged ship PR, and +AUTO-OPENS the alignment PR (`bugfix` → master). Merging the alignment PR +closes the cycle and auto-cuts the next lane (stage P4). No mechanism labels, +no direct pushes, no closeout step — nothing is stored. (LEGACY, retired with the same change: the "Release (one-click)" `train` dispatch — bump the lane / open a ship PR vs master / publish on that merge — @@ -394,21 +446,23 @@ SHA-differing cherry-pick is the price of leak safety, and `lane-leak-guard.yml` fails any lane push whose history contains a merge whose second parent is a master ancestor. -**CI wiring:** the lane's required checks are the `gate` contexts — one per -e2e-lane workflow (`ci-e2e-*.yml`), each that workflow's scope-decision job, -green on every non-ci:full PR (verified live on a lane PR, #4653 review -2026-10-25: `gate` success while all e2e suites report skipped). REVIEW -FINDING of that pass: although ci.yml's pull_request filter lists `bugfix-v*`, -lane PRs currently produce NO core-matrix check contexts (no plan/test/ -static-gates at the PR head) — treat "core matrix on lane PRs" as aspirational -until that trigger demonstrably fires; it does not gate merges today. What -actually gates a publish is structural: at ship time the post-merge sha is -brand-new, so `release-bugfix.yml` dispatches whatever is missing of the FULL -matrix at the exact publish sha and waits for green before npm publish (hard -fail; fast-mode skip = owner-owned risk, see the workflow). Pushes to -`bugfix-v*` still match ci.yml's push trigger (moot under protected lanes — -direct pushes are forbidden). The `ci.yml` version-guard allowlists `bugfix-v*` -heads (the lane carries its one legal bump commit, made at cut time). +**CI wiring (v3):** lane carry PRs produce the per-e2e-workflow `gate` +contexts (scope-decision jobs, green while e2e suites report skipped) — those +are the lane's required checks (verified live on #4577: 16× `gate` success, +every e2e suite context present-as-skipped). SHIP PRS (into `bugfix`) get the +real deal: ci.yml runs FULL scope for base=`bugfix` (the 16-leg test matrix +under its legacy `test (...)` shard names + static gates) and the `ci:full` +label rides all eight e2e lanes green — so the gate branch's required-checks +list is the ship PR's observed context roster, i.e. full gating realized +literally where a green full suite is actually achievable. Pushes to +`bugfix-v*`/`bugfix` still match ci.yml's push trigger (moot under protection +— direct pushes are forbidden). The `ci.yml` version-guard allowlists +`bugfix-v*` heads (the lane carries its one legal bump commit, made at cut +time). Whatever a ship PR does not cover is closed structurally: at publish +time the post-merge sha is brand-new, so `release-bugfix.yml` dispatches +whatever is missing of the FULL matrix at the exact publish sha and waits for +green before npm publish (hard fail; fast-mode skip = owner-owned risk, see +the workflow). ## CI publish mechanism (what release.yml does) From 7ad68109bc855d88a5f72036fc38b7287b8abc02 Mon Sep 17 00:00:00 2001 From: ranxianglei Date: Sun, 25 Oct 2026 16:31:02 +0800 Subject: [PATCH 2/6] docs(release): record the v2-arming self-fire incident (2026-10-25) and why v3 has no arming step --- reference/release.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/reference/release.md b/reference/release.md index 737a1cf9da..0f7627d2ce 100644 --- a/reference/release.md +++ b/reference/release.md @@ -243,6 +243,20 @@ the alignment PR (**head = `bugfix`**, base = master). Every other close — any PR into a lane, any non-tag-branch into `bugfix`, a non-merged close, a fork — is a millisecond no-op. +**Why v3 has no arming step (2026-10-25 incident — never re-arm lanes):** the +v2 design carried a separate "arming" commit to each new lane (the lane-side +copy of this workflow). The window proved fatal once: when arming PR #4654 +merged into `bugfix-v0.1.206`, GitHub resolved the `pull_request_target` event +against the base ref *after* the merge commit had landed — so the arm's own +trigger matched its own merge and immediately published v0.1.207 +(tag `7e69b49f`, GH Release 08:09:37Z) with none of the review the channel is +supposed to provide. No double-ship followed: every later close against that +frozen lane hits the monotonic npm guard (`0.1.207` already live) and dies red +without publishing. The lesson, codified in the model: **an arming commit +whose trigger matches its own target fires itself.** Hence the gate branch is +born carrying the workflow (no arming step exists in v3) and merges into tag +lanes can never fire anything. + Ship PRs run the COMPLETE suite: ci.yml forces FULL scope for base=`bugfix` (no label needed), and the e2e lanes ride the standard `ci:full` label on the ship PR. Belt-and-braces, the publish pipeline ALSO dispatches whatever is From 843a37faee2ecdef533ecd09417526ffe9e6b83f Mon Sep 17 00:00:00 2001 From: ci-check Date: Sun, 25 Oct 2026 17:03:01 +0800 Subject: [PATCH 3/6] fix(ci): allow the v3 gate-branch head shapes through version-guard (#4660) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review of the v3 model found the guard deadlocks the cycle at P3: the auto-opened alignment PR (head=bugfix, base=master) legitimately carries the shipped version bump into master, and backport carry branches inherit the lane pre-bump — neither shape matched the allowlist, so both would fail this guard on every cycle. Extend the allowlist with bugfix and backport/carry-* (ship lanes already pass via bugfix-v*). --- .github/workflows/ci.yml | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 46319fc394..091be19ecd 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -395,7 +395,11 @@ jobs: set -euo pipefail BRANCH="${GITHUB_HEAD_REF}" # Release + bugfix carve-out branches (#2851/#2853) may bump version — one isolated 'release v{VERSION}' commit each. - if [[ "$BRANCH" == *_release-v* || "$BRANCH" == bugfix-release/* || "$BRANCH" == bugfix-v* ]]; then + # v3 gate-branch model (#4660): tag lanes keep their ONE legal pre-bump commit (made at cut time); the + # auto-opened alignment PR (head=bugfix) carries that bump into master, and backport carry branches + # (backport/carry-N) inherit it from their lane base — all three head shapes must pass this guard or the + # cycle deadlocks at P3 (alignment never merges → next lane never auto-cuts). + if [[ "$BRANCH" == *_release-v* || "$BRANCH" == bugfix-release/* || "$BRANCH" == bugfix-v* || "$BRANCH" == bugfix || "$BRANCH" == backport/carry-* ]]; then echo "✓ release branch ($BRANCH) — version changes allowed" exit 0 fi From e9b8c0541d0a1dec6c34b608d565326999671ab0 Mon Sep 17 00:00:00 2001 From: ci-check Date: Sun, 25 Oct 2026 17:03:01 +0800 Subject: [PATCH 4/6] fix(ci): repair the v3 publish/auto-cut step shell defects (#4660) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review of the v3 model found four defects in the new step shells: - MANUAL_CMDS ended in an unterminated single quote, so bash rejected the ENTIRE auto-cut script before it could run (P4 could never succeed). - the final notice referenced $NEW_lane under set -u (defined var is NEW_LANE) — an unbound-variable crash after the push already succeeded. - the drift warning compared the LANE head against the ship MERGE sha, which lives on `bugfix`, never on the lane — it would warn on every non-ff ship. Compare against the reviewed lane tip (ship PR head sha, threaded as a new resolve output) instead. - the cycle-close notice printed an empty $VER on publish paths (resolve only sets it for cuts); read it from the version step. --- .github/workflows/release-bugfix.yml | 31 +++++++++++++++++++--------- 1 file changed, 21 insertions(+), 10 deletions(-) diff --git a/.github/workflows/release-bugfix.yml b/.github/workflows/release-bugfix.yml index 439aa8eb83..7dd4f4499e 100644 --- a/.github/workflows/release-bugfix.yml +++ b/.github/workflows/release-bugfix.yml @@ -108,6 +108,7 @@ jobs: BRANCH="" SHA="" VER="" + HEADSHA="" TITLE="$(jq -r '.pull_request.title // ""' "$GITHUB_EVENT_PATH")" if [ "$GITHUB_EVENT_NAME" = "pull_request" ]; then # LEGACY one-off carve-out: PR against master whose head is the @@ -133,6 +134,7 @@ jobs: PATH=publish BRANCH="$HEADREF" SHA="$(jq -r '.pull_request.head.sha' "$GITHUB_EVENT_PATH")" + HEADSHA="$SHA" elif [ "$GITHUB_EVENT_NAME" = "pull_request_target" ]; then MERGED="$(jq -r '.pull_request.merged' "$GITHUB_EVENT_PATH")" STATE="$(jq -r '.pull_request.state' "$GITHUB_EVENT_PATH")" @@ -159,6 +161,7 @@ jobs: PATH=publish BRANCH="$HEADREF" SHA="$(jq -r '.pull_request.merge_commit_sha' "$GITHUB_EVENT_PATH")" + HEADSHA="$(jq -r '.pull_request.head.sha' "$GITHUB_EVENT_PATH")" echo "::notice::SHIP PR detected: $HEADREF -> bugfix @ ${SHA:0:12} — publishing the post-merge lane head" # ---- path B: the alignment landed — auto-cut the next lane ---- elif [ "$BASE" = "master" ] && [ "$HEADREF" = "bugfix" ]; then @@ -197,6 +200,7 @@ jobs: echo "path=$PATH" >> "$GITHUB_OUTPUT" echo "branch=$BRANCH" >> "$GITHUB_OUTPUT" echo "sha=$SHA" >> "$GITHUB_OUTPUT" + echo "headsha=$HEADSHA" >> "$GITHUB_OUTPUT" echo "ver=$VER" >> "$GITHUB_OUTPUT" - uses: actions/checkout@v4 @@ -218,7 +222,7 @@ jobs: set -uo pipefail VER="${{ steps.resolve.outputs.ver }}" NEW_LANE="bugfix-v$VER" - MANUAL_CMDS='git fetch origin tag v'"$VER"' --no-tags && git checkout -b '"$NEW_LANE"' v'"$VER" && (edit package.json version to the next patch) && git commit -am "release: cut $NEW_LANE from v$VER" && git push origin '"$NEW_LANE" + MANUAL_CMDS='git fetch origin tag v'"$VER"' --no-tags && git checkout -b '"$NEW_LANE"' v'"$VER" && (edit package.json version to the next patch) && git commit -am "release: cut $NEW_LANE from v$VER" && git push origin "$NEW_LANE" fail() { echo "::error::$1" gh pr comment "$GITHUB_EVENT_NUMBER" --body "❌ **Auto-cut failed**: $1\n\nManual recovery:\n\`\`\`bash\n$MANUAL_CMDS\n\`\`\`\nThen protect \`$NEW_LANE\` exactly like master (reference/release.md § Lane protection)." \ @@ -243,25 +247,31 @@ jobs: SHA="$(git rev-parse HEAD)" gh pr comment "$GITHUB_EVENT_NUMBER" --body "✅ **Stage P4 complete** — lane \`$NEW_LANE\` auto-cut from tag \`v$VER\` (@ ${SHA:0:12}), package.json pre-bumped to \`$NEXT\`. One manual step remains before it takes on carries: apply the same protection as master (Settings → Branches → \`$NEW_LANE\`; payload: reference/release.md § Lane protection). Carry PRs (backport label) can start immediately." \ || echo "::warning::could not annotate PR $GITHUB_EVENT_NUMBER (non-fatal)" - echo "::notice::lane cycle advanced: next lane $NEW_lane ready (unprotected until the owner clicks)" + echo "::notice::lane cycle advanced: next lane $NEW_LANE ready (unprotected until the owner clicks)" - name: Switch to the publish tree (post-merge lane head / legacy pre-merge head) # v3 path A: publish the EXACT reviewed state — the merge sha of the # ship PR that just landed in `bugfix`. Legacy: pre-merge head of a - # merged carve-out PR. If the LANE head has moved past the merge sha - # (another carry landed while this run queued behind the ship PR under - # the concurrency group), warn loudly and still publish the reviewed - # sha; content past a SHIPPED lane never rides another release of that - # lane (the monotonic guard freezes it) — move it forward to master - # and carry it into the NEXT lane. + # merged carve-out PR. If the LANE head has moved past the reviewed + # ship state (another carry landed while this run queued behind the + # ship PR under the concurrency group), warn loudly and still publish + # the reviewed sha; content past a SHIPPED lane never rides another + # release of that lane (the monotonic guard freezes it) — move it + # forward to master and carry it into the NEXT lane. if: steps.resolve.outputs.path == 'publish' && steps.resolve.outputs.sha != '' run: | SHA="${{ steps.resolve.outputs.sha }}" BRANCH="${{ steps.resolve.outputs.branch }}" + HEADSHA="${{ steps.resolve.outputs.headsha }}" git rev-parse --verify --quiet "${SHA}^{commit}" >/dev/null || git fetch origin "$SHA" LIVE_HEAD="$(git ls-remote origin "refs/heads/$BRANCH" | awk '{print $1}')" - if [ -n "$LIVE_HEAD" ] && [ "$LIVE_HEAD" != "$(git rev-parse ${SHA}^{commit})" ]; then - echo "::warning::lane '$BRANCH' head ($LIVE_HEAD) is past the ship merge sha ($SHA) — publishing the reviewed merge sha only; anything newer on the lane is FROZEN out of this lane's releases (monotonic guard) and must ride master/the next lane" + # Drift reference = the lane tip reviewed at ship time (the ship PR's + # head sha). Comparing against the MERGE sha would warn on every ship: + # that commit lives on `bugfix`, never on the lane. + DRIFT_REF="$HEADSHA" + [ -z "$DRIFT_REF" ] && DRIFT_REF="$SHA" + if [ -n "$LIVE_HEAD" ] && [ "$LIVE_HEAD" != "$(git rev-parse ${DRIFT_REF}^{commit} 2>/dev/null)" ]; then + echo "::warning::lane '$BRANCH' head ($LIVE_HEAD) is past the reviewed ship state ($DRIFT_REF) — publishing the reviewed merge sha ($SHA) only; anything newer on the lane is FROZEN out of this lane's releases (monotonic guard) and must ride master/the next lane" fi git checkout --detach "$SHA" @@ -511,4 +521,5 @@ jobs: if: steps.resolve.outputs.path == 'publish' run: | LANE="${{ steps.resolve.outputs.branch }}" + VER="${{ steps.version.outputs.version }}" echo "::notice::shipped '$LANE' — the fresh tag v$VER freezes this lane (the monotonic guard refuses to re-publish it); the next lane is auto-cut from the tag once master is aligned" From 85c9a5ee8f3d7163bb32969141fd204c76c187a2 Mon Sep 17 00:00:00 2001 From: ci-check Date: Sun, 25 Oct 2026 17:03:01 +0800 Subject: [PATCH 5/6] fix(ci): scan master-cut lanes from their fork point, not the base tag (#4660) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The epoch-1 transition (reference/release.md) cuts the first v3 lane from ALIGNED MASTER, whose window from the nearest tag contains ordinary post-tag master merges — the guard false-alarmed 'lane leak detected' and its rebuild-from-tag advice would re-inherit the stale pre-v3 workflow file (the self-fire hazard v3 removes). When the lane forked from master strictly after its base tag, rescan from the fork point. Simulated all four lane species: tag-cut clean / nested carve-out unchanged-green, master-cut now green, real master-merge still RED. --- .github/workflows/lane-leak-guard.yml | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/.github/workflows/lane-leak-guard.yml b/.github/workflows/lane-leak-guard.yml index af42d28c70..0ad4b29fa5 100644 --- a/.github/workflows/lane-leak-guard.yml +++ b/.github/workflows/lane-leak-guard.yml @@ -32,6 +32,18 @@ jobs: git fetch -q origin master --tags BASE_TAG="$(git describe --match 'v[0-9]*' --tags --abbrev=0 HEAD || true)" [ -n "$BASE_TAG" ] || { echo "::error::cannot find the lane's base tag — refusing to skip the scan"; exit 1; } + # A lane deliberately cut from aligned MASTER (v3 epoch-1 transition, #4660) + # carries master's post-tag merges BY DESIGN — scanning from the base tag + # would flag them as leaks (and its "rebuild from the tag" advice would + # re-inherit the stale pre-v3 workflow file). When the lane forked from + # master strictly AFTER its base tag, rescan from the fork point: the + # window then covers exactly the commits the lane adds over master. + FORK="$(git merge-base HEAD origin/master 2>/dev/null || true)" + BASE_SHA="$(git rev-parse "${BASE_TAG}^{commit}")" + if [ -n "$FORK" ] && [ "$FORK" != "$BASE_SHA" ] && git merge-base --is-ancestor "$BASE_SHA" "$FORK"; then + echo "::notice::$BRANCH forked from master at ${FORK:0:12} (strictly past base tag $BASE_TAG) — scanning ${FORK:0:12}..HEAD instead" + BASE_TAG="$FORK" + fi LEAKS="$(git log --format=%H --merges "${BASE_TAG}..HEAD" \ | while read -r M; do P2="$(git rev-parse "${M}^2" 2>/dev/null || echo "")" From a7db582a1f7b92397000bbeef19c4196e0794f67 Mon Sep 17 00:00:00 2001 From: ci-check Date: Sun, 25 Oct 2026 17:03:01 +0800 Subject: [PATCH 6/6] docs(release): spell out the epoch-1 transition (first v3 lane comes from aligned master) The issue body states the design but the shipped doc never said how to get past the one stale artifact left by the incident: tag v0.1.207's tree carries the v2 wide trigger, and backport.yml auto-cuts a missing lane from the latest tag on demand. Add the ordered procedure (including the do-not-label-backport window and advisory bc-2026-001's frozen old target) plus the two accepted consequences of cutting from aligned master. --- reference/release.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/reference/release.md b/reference/release.md index 0f7627d2ce..5dc097e3e4 100644 --- a/reference/release.md +++ b/reference/release.md @@ -257,6 +257,39 @@ whose trigger matches its own target fires itself.** Hence the gate branch is born carrying the workflow (no arming step exists in v3) and merges into tag lanes can never fire anything. +**Epoch-1 transition (2026-10-25 — the first v3 lane is special; do it in order):** +tag `v0.1.207`'s published tree still carries the **v2** workflow file (it IS the +self-fired arm's tree), and `pull_request_target` executes the **base-side** copy — +so the first v3 lane must be cut from **aligned master**, NOT from that tag: a lane +inheriting the v2 wide trigger would self-fire its FIRST carry merge straight into a +publish — the same incident, delivered by `backport.yml`, which AUTO-CUTS a missing +lane from the latest tag the moment any PR gets the `backport` label. Procedure: +1. merge this PR (#4660) into master; +2. merge the open alignment PR #4659 ("align master with v0.1.207 …") — it currently + conflicts against master, resolve/rebase first. After it, master equals npm latest + AND carries the v3 doc. (The two merges are order-safe: with v3 live, #4659's head + `bugfix-v0.1.206` matches neither path and no-ops; with v2 live, base=`master` + matches no trigger at all); +3. create + protect the `bugfix` gate branch from master (payload above); +4. manually cut the first v3 lane from ALIGNED MASTER (same recipe as the auto-cut + step's manual-recovery block, base swapped for aligned master), pre-bump + package.json to the next patch over npm latest (`0.1.208`), protect it (same payload); +5. do NOT apply `backport` labels before step 4 lands — they would auto-cut + `bugfix-v0.1.207` from the stale tag instead; +6. carry the outstanding fixes into the new lane — including advisory bc-2026-001 + (#4655): its original target `bugfix-v0.1.206` is frozen by the monotonic guard + and can never ship it; +7. open the ship PR (lane → `bugfix`, label `ci:full`) and merge = publish `0.1.208`. + +Two accepted consequences of cutting from aligned master: the epoch-1 push trips +`lane-leak-guard.yml`'s tag-based window unless the fork-point baseline shipped with +#4660 is present (it is), and the epoch-1 publish ships everything master held at cut +time — the narrow "tag + fixes only" property is lost for this ONE cycle only; every +later lane is auto-cut from its freshly shipped tag, whose tree carries the v3 file, so +the property holds indefinitely after that. (The alternative — cut from the stale tag +and carry the v3 workflow file in as an inert first commit — was rejected: it strands +the tag stream on the v2-era ci.yml, so lane PRs lose the core matrix permanently.) + Ship PRs run the COMPLETE suite: ci.yml forces FULL scope for base=`bugfix` (no label needed), and the e2e lanes ride the standard `ci:full` label on the ship PR. Belt-and-braces, the publish pipeline ALSO dispatches whatever is