Skip to content

Commit 1491787

Browse files
ci(release): add the dispatch-only next snapshot lane (ADR-0125 amendment) (#30799)
<!-- claude-projects-attribution: {"github_login":"marchtian"} --> _Requested by **田騏** · [project thread](https://claude.ai/code/project/chan_01VmuUhXU9SSUzqJYyXSmYSi?thread=cmsg_01VmuUhXU9SSUzqJYyXSmYSiNjyvCdXYygFqntMNR7S2dW)_ Part of #30591 Ruling-ref: 6663894403 Clause-②: no Metadata-protocol: none ## 维护者速读 - **改了什么**:Release 工作流新增一条只能手动触发的 `next` 快照通道。勾选 `snapshot_next` 并在 `release` 环境批准后,它把 main 上最新一个全量测试在本提交上全绿的版本,以 `0.0.0-next-时间戳` 发布到 npm 的 `next` 标签。不打 git tag,不建 GitHub Release,不碰 Version Packages PR,不动 `latest`。 - **为什么改**:ADR-0125 的 2026-11-05 修订(#29466 的裁决)要求:应用方当天就需要的修复,可以先装 `next`,不必等下一个稳定版;用 `latest` 的用户没有任何变化。 - **风险与回滚**:快照触发与稳定通道互斥。稳定通道三个 job 的 `if:` 只做减法,另有自测钉住。审批页上的任务名与稳定发布的提示不同,不会被当成稳定发布批准。回滚就是 revert 本 PR;已发布的快照只占 `next`,下一次稳定发布会把 `next` 移回稳定版。注意:`@objectstack/service-push` 还没在 npm 首发,在稳定通道首发它之前,本通道会拒绝发布(这是设计要求)。 - **先看**:① `.github/workflows/release.yml`:文件末尾两个新 job,以及 `release-integrity` / `full-battery` / `publish` 三处新增的 `!inputs.snapshot_next`;② `scripts/ci/snapshot-next.mjs`:`guard` 与首发规则 `debutRefusals`;③ `scripts/release-snapshot-publish.sh`:唯一的发布命令行。 - **两分钟验证**:运行 `node scripts/ci/snapshot-next.mjs --self-test`,预期最后一行是 `snapshot-next: self-test OK -- 68 case(s) across 11 batteries`。 - **需要你做的**:等席位的独立契约评审通过后,审阅并合并本 PR(`release.yml` 是受管面)。 ## What changes ADR-0125's `## Amendment (2026-11-05, #29466)` lists what the lane must satisfy. Each item and where this PR meets it: - **Dispatch-only and exclusive.** A new `workflow_dispatch` input, `snapshot_next` (boolean, default false), selects the lane. `release-integrity`, the stable `full-battery` gate (force branch) and `publish` (force branch) now also require `!inputs.snapshot_next`. These are strictly subtractive `if:` edits, the same shape as `!inputs.refresh_version_pr`. The two new jobs run only on `workflow_dispatch && inputs.snapshot_next && !inputs.refresh_version_pr`. `stale-prompts`, `version-pr` and `docker` are unchanged. A snapshot dispatch therefore queues no stable prompt that the stale-prompt sweep could not reach. Combined inputs: - snapshot + refresh runs `version-pr` only, following the existing refresh-wins precedent. - snapshot + force runs the snapshot lane only; `force` is never read there. - **The commit, distance zero.** `scripts/ci/scheduled-full-run.mjs` gains machine-readable output: - `--json`: stdout carries exactly one JSON record and prose goes to stderr. - `--require-distance-zero`: refuses unless each gate workflow's deciding run is ON the release commit. - `--snapshot-commit --from SHA`: walks main's first-parent history and picks the newest commit at which both CI and Lint & Type Check decide green at distance zero. - `releaseGateVerdict` now also returns `chosen` rows and `distanceZero`. The stable `--release-gate` output and verdict are unchanged when the new flag is absent. - The preflight selects the commit with `--snapshot-commit`, confirms it with `--release-gate --release-commit C --require-distance-zero --json`, and checks the record with `jq`. The publish job checks out exactly that commit and re-asserts that it is an ancestor of `origin/main`. - **Not during an RC cycle.** `snapshot-next.mjs preflight` refuses when `.changeset/pre.json` exists with `mode: pre` (`preModeRefusal`). - **Workspace only.** The publish job runs the bare `pnpm exec changeset version --snapshot next` (never `pnpm run version`) and asserts the version is `0.0.0-next-` followed by 14 digits. It commits nothing, and its checkout holds no push credential (`persist-credentials: false`, `contents: read`). It then runs `bash scripts/release-snapshot-publish.sh`, whose one publish line is `changeset publish --tag next --no-git-tag`. The script is preceded by the same `check-published-dist-tooling --no-build` refusal the stable publish runs. There is no tag push, no GitHub Release and no Version Packages PR write. - **The guard and the debut rule.** `scripts/ci/snapshot-next.mjs` (new, with `--self-test`): - `preflight` reads every member of the 109-package fixed group on npm (abbreviated packument). It refuses on any member with no version (`debutRefusals`), and fails closed on any unread member. Today that is `@objectstack/service-push`. - `guard` runs before the publish. It checks that: - the fixed group equals the publishable set, and every member is at one snapshot version; - no `publishConfig.tag`, `.npmrc` `tag=` or `npm_config_tag` overrides the tag (no value is printed); - the `changeset publish-plan` covers the whole group; - every packed manifest (`changeset pack`, so pnpm has substituted `workspace:`) carries the snapshot version, holds no `workspace:` range, and has every intra-group range satisfied by the snapshot. - `verify` runs after the publish. It reads `next` back at the snapshot version and treats any `latest` move onto a snapshot as an incident. ⛔ Nothing in the lane writes `latest`. - **The approval screen.** `snapshot-next` is held at `environment: release`. Its name is `Snapshot next of main COMMIT (awaiting approval)`, and the self-test pins that it does not match `PUBLISH_JOB_NAME` from `release-pending-publish.mjs`. It has its own concurrency group, `release-snapshot-next-REF` with `cancel-in-progress: false`, so a waiting snapshot never holds `release-publish-REF`. - **The dry run.** `node scripts/ci/snapshot-next.mjs dry-run` runs the preflight, the version step and the guard's pack. It prints each package with its version, dist-tag and intra-group ranges, then restores the tree. It publishes nothing and reads no token. The preflight job runs it on every snapshot dispatch, before approval. - **Docs.** The release-channels table in `docs/releases-maintenance.md` gains the snapshot `next` row, plus a paragraph on sort order and on AI seats never dispatching the lane. - **Gates that read release.yml.** - `scripts/pm/fleet-write/validate.mjs`: pins for the declared inputs and the job roster (eight jobs), and the mutation anchor for `release-integrity`'s guard. - `.github/workflows/lint.yml`: wires `snapshot-next.mjs --self-test` (step id `snapshot-lane-guard-self-test`). ## Tests - `node scripts/ci/snapshot-next.mjs --self-test`: 68 cases across 11 batteries. Coverage includes: - Pre-mode refusal, debut refusal, tag overrides, plan and packed-manifest problems, and the verify incident rules. - Mutation cases on the real release.yml and the publish script. Each fires when an `if:` negation, the environment, the name shape, the bare version command or the publish line is removed or reshaped. - Exclusivity evaluated through fleet-write's own `jobsStartedBy` over every event and input combination. Push, schedule, repair, force and refresh never reach the snapshot jobs. A snapshot dispatch reaches no stable job. - `node scripts/ci/scheduled-full-run.mjs --self-test`: a new battery, "release gate: distance zero and the snapshot commit, machine-readable" (11 cases). The battery floor was raised from 7 to 8. On the recorded fixture, the stable gate verdict is unchanged. - `pnpm check:pm-fleet-write-validate`: 329 cases pass with the updated pins. ## Acceptance notes - Acceptance item 1 (the dry run) is met. Its output is below. - Acceptance item 2 (the first real snapshot's `npm view` reading) waits for `@objectstack/service-push` to debut through the stable lane, which is why this PR says `Part of`. - Version shape: changesets v3 with no snapshot template yields `0.0.0-next-YYYYMMDDHHMMSS`. The docs table spells that shape. - The publish job also runs `release-spec-changes.sh --generate` and then `--verify`, so the spec tarball ships its two ADR-0087 projections, as the stable publish does. The snapshot lane builds no Docker image, runs no dist-tag sweep and cuts no GitHub Release. - The dry run owns the tree while it runs. It refuses a dirty tree, then restores tracked paths with `git restore` and removes only the untracked files it created. ## Verification <details> <summary>Dry run on 75a0ac4 (local, no publish, no npm token): REFUSED on the debut rule, guard clean</summary> ```text snapshot-next dry-run: nothing is published, tagged or pushed; no npm token is read. preflight: 109 fixed-group member(s) read on npm; 1 refusal(s), 0 unread. REFUSED @objectstack/service-push has no version on npm: its first publish would take `latest` whatever tag it carries. The stable lane debuts it; no snapshot is cut until it has. version: changeset version --snapshot next (bare; never `pnpm run version`) version step moved 611 path(s): 122 package.json, 122 CHANGELOG.md, 367 .changeset/ file(s), 0 other -- none of it is ever committed. guard: 109 member(s) · version 0.0.0-next-20261106032733 · tag next · planned 109 · packed 109 · 540 intra-group range(s) in the packed manifests, all checked against the snapshot would publish (name · version · dist-tag · intra-group ranges in the packed manifest): @object-ui/auth · 0.0.0-next-20261106032733 · next · 1 @object-ui/cli · 0.0.0-next-20261106032733 · next · 4 ... (109 rows, every one at tag next; full list in the os-dev-report on the card) @objectstack/cli · 0.0.0-next-20261106032733 · next · 52 @objectstack/runtime · 0.0.0-next-20261106032733 · next · 21 @objectstack/service-push · 0.0.0-next-20261106032733 · next · 2 @objectstack/spec · 0.0.0-next-20261106032733 · next · 0 @objectstack/verify · 0.0.0-next-20261106032733 · next · 35 create-objectstack · 0.0.0-next-20261106032733 · next · 0 tree: restored to HEAD VERDICT: REFUSED -- 1 preflight refusal(s), 0 unread, 0 guard problem(s). The lane would publish nothing. ``` </details> <details> <summary>Derived gates on 75a0ac4: 67 derived, 67 run, all exit 0; --ran reconciled</summary> ```text node scripts/check-adr-links.mjs (+ --self-test) :: exit 0 node scripts/check-closing-keyword-parity.mjs (+ --self-test) :: exit 0 node scripts/check-comment-mask-corpus.mjs :: exit 0 node scripts/check-declaration-mirrors.mjs (+ --self-test) :: exit 0 node scripts/check-merged-branch-reaper-outcome.mjs (+ --self-test) :: exit 0 node scripts/check-self-test-wired.mjs (+ --self-test) :: exit 0 node scripts/check-self-test-workflow-commands.mjs (+ --self-test) :: exit 0 node scripts/check-step-collectors.mjs (+ --self-test) :: exit 0 node scripts/check-whole-set-label-write.mjs (+ --self-test) :: exit 0 node scripts/ci/plan-test-core-shards.mjs --self-test :: exit 0 node scripts/ci/scheduled-full-run.mjs --self-test :: exit 0 node scripts/ci/snapshot-next.mjs --self-test :: exit 0 node scripts/docs-audit/check-drift-comment.mjs :: exit 0 node scripts/pm/bare-root-worklist.mjs --self-test :: exit 0 node scripts/pm/ci-failure.mjs --self-test :: exit 0 node scripts/release-dist-tags.mjs --self-test :: exit 0 node scripts/release-verify-npm.mjs --self-test :: exit 0 pnpm --filter @objectstack/lint run check:doc-formula-expressions :: exit 0 pnpm check:agent-test-spelling :: exit 0 pnpm check:aggregator-roster :: exit 0 pnpm check:bash32-floor :: exit 0 pnpm check:ci-filter-parity :: exit 0 pnpm check:cli-command-ids :: exit 0 pnpm check:cross-package-test-inputs :: exit 0 pnpm check:declared-population-live :: exit 0 pnpm check:doc-authoring :: exit 0 pnpm check:driver-memory-census :: exit 0 pnpm check:entry-guard :: exit 0 pnpm check:gitlink-declared :: exit 0 pnpm check:node-version :: exit 0 pnpm check:nul-bytes :: exit 0 pnpm check:parse-guard :: exit 0 pnpm check:pm-close-cards :: exit 0 pnpm check:pm-dispatch-gates :: exit 0 pnpm check:pm-expected-skips :: exit 0 pnpm check:pm-fleet-write-dispatch :: exit 0 pnpm check:pm-fleet-write-execute :: exit 0 pnpm check:pm-fleet-write-validate :: exit 0 pnpm check:pm-governed-merges :: exit 0 pnpm check:pm-issue-create :: exit 0 pnpm check:pm-issue-transfer :: exit 0 pnpm check:pm-label-write :: exit 0 pnpm check:pm-post-stamped :: exit 0 pnpm check:pm-record-recognisers :: exit 0 pnpm check:pnpm-acquisition :: exit 0 pnpm check:pnpm-filter-targets :: exit 0 pnpm check:pnpm-flag-spellings :: exit 0 pnpm check:refd-timer-probe :: exit 0 pnpm check:required-contexts :: exit 0 pnpm check:scripts-symbol-anchors :: exit 0 pnpm check:select-gate-families :: exit 0 pnpm check:shard-attestation :: exit 0 pnpm check:stall-guard-budget :: exit 0 pnpm check:stall-guard-headroom :: exit 0 pnpm check:type-check-coverage :: exit 0 pnpm check:type-check-debt :: exit 0 pnpm check:watch-hint-literal :: exit 0 pnpm check:workflow-status-functions :: exit 0 pnpm check:workflow-step-name-quoting :: exit 0 Run reconciliation — 67 derived, 67 run, 0 NOT-MEASURED, 0 UNRUN. ``` `check:doc-formula-expressions` first exited 3 (its build prerequisite was missing). It went green after building `@objectstack/formula` and `@objectstack/lint`. </details> `skip-changeset`: the diff touches only `.github/workflows/**`, `scripts/**` and `docs/**`, none of which is in any package's `files[]`. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 0cba0ce commit 1491787

7 files changed

Lines changed: 1959 additions & 37 deletions

File tree

‎.github/workflows/lint.yml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3152,6 +3152,15 @@ jobs:
31523152
continue-on-error: true
31533153
run: node scripts/release-dist-tags.mjs --self-test
31543154

3155+
# Rationale: `scripts/ci/snapshot-next.mjs` header (ADR-0125, amendment of
3156+
# 2026-11-05). The `next` snapshot lane's guard and debut rule; its last
3157+
# two batteries read release.yml and evaluate every job's `if:` for the
3158+
# snapshot dispatch, so the lane's exclusivity is pinned on every PR.
3159+
- name: Snapshot lane guard self-test
3160+
id: snapshot-lane-guard-self-test
3161+
continue-on-error: true
3162+
run: node scripts/ci/snapshot-next.mjs --self-test
3163+
31553164
# Release version-commit selection (ADR-0125 D1 as amended 2026-09-29).
31563165
# release.yml's publish lane queues a deployment only on the push that
31573166
# CARRIES the version commit, publishes that commit rather than a later

‎.github/workflows/release.yml‎

Lines changed: 343 additions & 13 deletions
Large diffs are not rendered by default.

‎docs/releases-maintenance.md‎

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -190,12 +190,19 @@ nothing.
190190

191191
### Release channels
192192

193-
There are two npm channels, and both are published by `release.yml`:
193+
There are two npm channels, and both are published by `release.yml`. `next` has two
194+
publishers and two version shapes:
194195

195196
| dist-tag | Carries | Published by |
196197
|---|---|---|
197-
| `latest` | the stable release (GA) | `release.yml`, outside pre mode — the Version Packages PR flow below |
198-
| `next` | the pre-release (`X.Y.Z-next.N`) | `release.yml` in pre mode: `.changeset/pre.json` says `mode: pre`, `tag: next`, and `changeset publish` publishes under that tag |
198+
| `latest` | the stable release (GA) | `release.yml`, outside pre mode — the Version Packages PR flow below. The only path that writes `latest` |
199+
| `next` | the pre-release (`X.Y.Z-next.N`) during a release-candidate cycle | `release.yml` in pre mode: `.changeset/pre.json` says `mode: pre`, `tag: next`, and `changeset publish` publishes under that tag |
200+
| `next` | a snapshot of `main` (`0.0.0-next-YYYYMMDDHHMMSS`) outside a cycle | `release.yml`'s snapshot lane: **Actions → Release → Run workflow** with `snapshot_next` checked, then a required reviewer approves `Snapshot next of main <commit> (awaiting approval)` at `environment: release`. It cuts the newest commit whose full battery is green on it, runs `changeset version --snapshot next` in the runner only (never committed), and runs `changeset publish --tag next --no-git-tag`: no tag, no GitHub Release, no Version Packages PR change, `latest` untouched. It refuses while `.changeset/pre.json` says `mode: pre` at the selected commit or at main's tip, read again after the approval (the cycle owns `next`) and while any fixed-group member has no version on npm (a first publish takes `latest`). ADR-0125, amendment of 2026-11-05 |
201+
202+
A snapshot version sorts below every stable version, so the next stable publish's
203+
dist-tag step moves `next` back up to it. An app that needs a fix the day it lands
204+
pins `next`; `latest` users see no change. ⛔ No AI seat dispatches the snapshot lane
205+
or approves its deployment (AGENTS.md Prime Directive 15).
199206

200207
There is no `rc` channel. The Cut RC lane that cut `X.Y.Z-rc.N` is retired and its
201208
workflow deleted, and a pre-release cycle enters pre mode with tag `next`, never `rc`.
@@ -228,8 +235,10 @@ waits at `environment: release` for a required reviewer to approve a job named
228235
`Publish <version> to npm (awaiting approval)` — the version read from the commit,
229236
never one you supply (ADR-0125 D1/D2). ⛔ **Actions → Release → Run workflow** is
230237
**not** the GA publish path: since ADR-0125 D4 that dispatch takes no version input at
231-
all, and left unchecked it starts the repair lane for a publish that died partway —
232-
checked, it starts the bookkeeping lane described next.
238+
all, and with neither `refresh_version_pr` nor `snapshot_next` checked it starts the
239+
repair lane for a publish that died partway — `refresh_version_pr` starts the
240+
bookkeeping lane described next, and `snapshot_next` the `next` snapshot lane above,
241+
which runs no stable job.
233242

234243
The cut, in order (each step is explained below):
235244

0 commit comments

Comments
 (0)