diff --git a/.github/workflows/api-diff.yml b/.github/workflows/api-diff.yml index f72902cac22..a318c46c9cd 100644 --- a/.github/workflows/api-diff.yml +++ b/.github/workflows/api-diff.yml @@ -2,8 +2,10 @@ name: API diff # Diffs every published API against its last release on PRs into `release`. # A backport fails on any break, since it must keep the published API. The cut -# (a PR from `main`) only reports, for the migration audit: release-plz bumps -# the versions after it lands, so its breaks are expected. +# (a PR from `main`) only reports, for the migration audit, unless the cycle's +# `phase` in version.json is `additive`: an additive cut publishes patches, so +# a break fails it. Nightly calls this on `main` and runs only in that phase, +# so a break that lands early surfaces within a day rather than at the cut. permissions: contents: read @@ -18,30 +20,51 @@ jobs: diff: name: Public API runs-on: ubuntu-24.04-arm + # Nightly's run on `main` writes the Rust cache, which needs this environment's keys. + environment: ${{ github.ref == 'refs/heads/main' && 'cache-write' || '' }} # cargo-semver-checks documents every published crate twice, baseline and current. timeout-minutes: 120 steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - - uses: ./.github/actions/nix - - uses: ./.github/actions/rust-cache + - name: Pick the mode + id: mode + run: | + # `release` has no version.json until the first shared cut lands there. + phase=null + if [[ -f version.json ]]; then phase=$(jq -r .phase version.json); fi + if [[ "$EVENT" != pull_request* ]]; then + # Nightly on `main`: only the additive phase forbids a break there. + [[ "$phase" == additive ]] && echo "args=--deny" >>"$GITHUB_OUTPUT" || echo "skip=1" >>"$GITHUB_OUTPUT" + elif [[ "$HEAD_REF" == main && "$HEAD_REPO" == "$GITHUB_REPOSITORY" && "$phase" != additive ]]; then + # Only this repository's own `main` is the cut; a fork's `main` is a backport. + echo "args=" >>"$GITHUB_OUTPUT" + else + echo "args=--deny" >>"$GITHUB_OUTPUT" + fi + env: + EVENT: ${{ github.event_name }} + HEAD_REF: ${{ github.head_ref }} + HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }} + - if: ${{ !steps.mode.outputs.skip }} + uses: ./.github/actions/nix + - if: ${{ !steps.mode.outputs.skip }} + uses: ./.github/actions/rust-cache with: access-key-id: ${{ secrets.MBX_R2_ACCESS_KEY_ID }} secret-access-key: ${{ secrets.MBX_R2_SECRET_ACCESS_KEY }} # The JS baseline is rendered from `release`'s source. - name: Fetch release + if: ${{ !steps.mode.outputs.skip }} run: git fetch --no-tags --depth=1 origin +refs/heads/release:refs/remotes/origin/release - name: Diff against the last release id: diff - run: | - mode=(--deny) - # Only this repository's own `main` is the cut; a fork's `main` is a backport. - [[ "$HEAD_REF" != main || "$HEAD_REPO" != "$GITHUB_REPOSITORY" ]] || mode=() - nix develop --command just api-diff "${mode[@]}" + if: ${{ !steps.mode.outputs.skip }} + # The report-only mode passes no argument. + run: nix develop --command just api-diff ${ARGS:+"$ARGS"} env: - HEAD_REF: ${{ github.head_ref }} - HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }} + ARGS: ${{ steps.mode.outputs.args }} # Lists and downloads the moq-c and moq-ffi release assets. GH_TOKEN: ${{ github.token }} - name: Keep the report diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml index cf6d6a9bde4..a71b6804cc7 100644 --- a/.github/workflows/nightly.yml +++ b/.github/workflows/nightly.yml @@ -89,6 +89,12 @@ jobs: oss-scanner: uses: ./.github/workflows/oss-scanner.yml + # Refuses a public API break on main while the cycle is additive, and skips + # otherwise (see RELEASE.md's Releases). + api-diff: + uses: ./.github/workflows/api-diff.yml + secrets: inherit + # Each independent workload gets its own hour. Each benchmark group keeps one # build environment, so a benchmark reuses the dependencies its group already # compiled. The Rust benchmarks outgrew one hour, so they split by harness: diff --git a/RELEASE.md b/RELEASE.md index f5ba2475760..9799a1e7e05 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -2,19 +2,32 @@ `main` is the trunk; `release` is what ships, and release-plz and every branch-triggered publish run only there. +After the `0.22.0` cut, which still waits on every break planned for it, each release cycle runs in three phases by kind of change, recorded as `phase` in `version.json`: `additive` work first, then `api` breaks, then `wire` changes. +An API break is what a published consumer adapts to when it rebuilds: the public Rust, JS, or bindings API, CLI flags, config keys, and environment variables. +A wire change is what a deployed peer adapts to without rebuilding: a frozen wire version, the hang catalog JSON, or a stored or exported container format. +The maintainer opens the next phase with a PR that changes `phase`. After the `0.22.0` cut, and after the wire cut that ends each cycle, a PR on `main` sets it to `additive` once the cut has merged into `release` and every package it bumps is published (crates.io, npm, and the `moq-c-v*`/`moq-ffi-v*` GitHub releases): the cut PR itself carries breaks, so its API diff must only report, and the API diff's baselines are those published versions, so an earlier reset fails Nightly's `--deny` on every break the cut shipped. +`main` can be cut on demand in the additive and API phases; in the wire phase it is cut only once its wire version is final, so wire work comes last and stays short. +While `phase` is `additive`, Nightly runs `just api-diff --deny` on `main` and the cut PR's API diff denies too, so a break that lands early is reverted, or the maintainer opens the API phase. + - Smoke clients call only the latest published APIs. A release cut updates `test/smoke/clients` to the APIs being published, then verifies the affected smoke lanes. -- A release is cut by hand: a PR merging `main` into `release`, with a merge commit. After the pre-cut merge of `release` into `main`, run `just version 0.22.0` on `main` for the first shared cut, or the next shared minor for later cuts. Commit the resulting versions and lockfiles before opening the cut PR. Run `just version` to check them. +- A release is cut by hand: a PR merging `main` into `release`, with a merge commit. After the pre-cut merge of `release` into `main`, run `just version 0.22.0` on `main` for the first shared cut, or the next shared minor for a later API or wire cut. Commit the resulting versions and lockfiles before opening the cut PR. Run `just version` to check them. - A breaking cut first writes, on `main`, each changed package's version-transition section in its `MIGRATE.md` (`## 0.3 -> 0.4`), the only `MIGRATE.md` edit `just check` allows, from the migration audit: the `!` subjects since the `release` merge base, each of those PRs' Impact section, and the API diff. -- Suggest a `release` backport for any serious bug fix (crash, security, data loss, broken interop), whether found on `main` or reported against a release. Land it on `main` first, then port it onto `release` as a separate PR that keeps the published API, so it ships as a patch. A backport quest or PR names "the next release", never a version number, since the `release` bump can land first. The Release gate's API diff (`just api-diff --deny`) fails a backport that changes one; on the cut PR, whose head is `main`, it only reports. +- Suggest a `release` backport for any serious bug fix (crash, security, data loss, broken interop), whether found on `main` or reported against a release. Land it on `main` first, then port it onto `release` as a separate PR that keeps the published API, so it ships as a patch. A backport quest or PR names "the next release", never a version number, since the `release` bump can land first. The Release gate's API diff (`just api-diff --deny`) fails a backport that changes one; on the cut PR, whose head is `main`, it only reports, unless `phase` is `additive`. - A bench-only backport ports `main`'s benchmarks onto `release`, so a pairing against `release` (`just bench origin/release`) compares them. It carries only benchmarks and their harness: bench targets, bench-only dev-dependencies, and `bench/`. It changes no shipped code, and it shims locally any API that `release` lacks, keeping each case's ID the same as on `main`. A case that measures code `release` doesn't have is left out, and the PR lists it. Merging one makes release-plz propose patch bumps for the crates it touches, though no shipped code changed. - After any release publishes, patch or breaking, run `just test wire-compat --remeasure` on `main` and land the rewritten `test/interop/compat/planned-breaks.json` with refreshed reasons. Otherwise the nightly wire-compat check fails on the stale pins. -- Nothing merges `release` into `main` automatically. Before cutting a minor or breaking release, the maintainer merges `release` into `main` once, so trunk carries the published versions, CHANGELOGs, and any `release`-only commits. It lands as a merge commit with `--admin`, never squashed, so the cut starts from an advanced merge base. +- Nothing merges `release` into `main` automatically. Before every cut, the maintainer merges `release` into `main` once, so trunk carries the published versions, CHANGELOGs, and any `release`-only commits. It lands as a merge commit with `--admin`, never squashed, so the cut starts from an advanced merge base. + +A cut's kind follows what it carries since the last cut: + +- An **additive** cut carries no break. It publishes patches: `just version` is not run, release-plz proposes Rust patches on `release`, and each changed JS package and binding wrapper takes a patch bump on `main` before the cut PR (Go derives its patch in CI; FFI packages follow their Rust crate). It runs the readiness checks: the release-to-main merge, the API diff (no break), `just test wire-compat`, package dry-runs, draft checks, all-language interop, and the smoke clients. +- An **API** or **wire** cut advances the shared minor with `just version`, so a wire cut after an API cut advances it again. Besides the readiness checks, it needs the migration audit (its `MIGRATE.md` sections) and the API shape, feature, and Cargo feature reviews of what changed since the last breaking cut. A wire cut also finalizes the cycle's wire version. # Versions Releases are cut separately; bump only when asked. Every published MoQ package -shares one minor across ecosystems, including unchanged packages at each cut. -The first shared cut is `0.22.0`; later cuts advance the minor together. Patch +shares one minor across ecosystems. The first shared cut is `0.22.0`; every +later API or wire cut advances the minor together, including unchanged +packages, and an additive cut publishes patches under the current minor. Patch versions stay independent per package, including Rust: release-plz has no `version_group`. @@ -32,7 +45,10 @@ resolving unrelated dependencies. It also advances Python, Dart, and Kotlin bindings requirements to the cut's minor while allowing independent patches. Rust requirements are updated by `release-plz set-version`; disposable changelogs keep published history intact. -The recipe records the shared minor and named exemptions in `version.json`. +The recipe records the shared minor and named exemptions in `version.json`, +which also holds the cycle's `phase` (see [Releases](#releases)); the check +accepts `null`, `additive`, `api`, or `wire`, and `null` disables the phase's +API-diff enforcement. `just version` checks it on every `just check` and `just ci`; enforcement is disabled while its minor is `null`, until the cut runs the recipe. Once active, the check rejects minor drift, unpromoted dependencies, stale exemptions, and diff --git a/quest/README.md b/quest/README.md index 19f5ad3323b..70c5e250044 100644 --- a/quest/README.md +++ b/quest/README.md @@ -34,13 +34,40 @@ change for the current cycle and by priority after it. This replaces m1 as could bury urgent breaking work behind additive work, so urgency still wins: urgent work of either kind joins m0. -Milestones shift after each cut (decided 2026-10-19, rule replaced -2026-11-05). The [release cut](/quest/m3/release/cut.md) recurs and performs -the shift: remaining release-execution quests move to m0, m3's quests split -by kind into m1 and m2, m4's move to m3, m4 starts empty, and m5 stays the -deferred bucket. The cut PR also re-creates the cut gate in m2. The hygiene -audits recur once per major release in m3, behind the cut, so the shift -brings each into m1. +After the next cut, each release cycle runs in three phases by kind of +change (decided 2026-11-09, maintainer): additive work, then API breaks, then +wire changes, as [Releases](/RELEASE.md#releases) describes. `main` is +cut on demand in the first two phases, so their cuts are no longer gated on a +milestone; the wire phase is short and its cut ends the cycle. An API break +is what a published consumer adapts to when it rebuilds: the public Rust, JS, +or bindings API, CLI flags, config keys, and environment variables. A wire +change is what a deployed peer adapts to without rebuilding: a frozen wire +version, the hang catalog JSON, or a stored or exported container format, +since a deployed peer parses those too. A change to an unpublished `-wip` +wire version is wire work. + +The next cut performs a re-split, and each cut that ends a cycle shifts the +milestones (decided 2026-10-19, rule replaced 2026-11-05 and 2026-11-09). The +[release cut](/quest/m3/release/cut.md) does both: + +- The next cut moves remaining release-execution quests to a release epic in + m0, where each cut re-creates its successor, and sorts m3's + other quests by kind: additive into m1, API breaks into m2, wire changes + stay in m3. m4 keeps its quests as later work of higher priority, m5 starts + empty as later work of lower priority, and today's m5 moves to m6, the + deferred bucket. m1 is then additive work, m2 API breaks, and m3 wire + changes. +- Each later cut that ends a cycle moves remaining release-execution quests + to m0, sorts m4's quests by kind into m1, m2, and m3, moves m5's to m4, and + leaves m5 empty and m6 the deferred bucket. + +Ordering holds the phases: m1 work ranks first, and while `phase` in +`version.json` is `additive`, Nightly and the cut refuse a public API break on +`main`. Wire work is held by planning alone: it waits in m3 until the +maintainer opens the wire phase. The cut gate is re-created in m3, which the +cycle's last cut waits on. The hygiene audits recur behind the cut in the +higher-priority later-work milestone (m3 until the next cut, m4 after it), so +the shift brings each into m1. The [release execution](/quest/m3/release/README.md) starts once m2 is done. It publishes artifacts before downstream adoption and rollout can complete. diff --git a/quest/m3/README.md b/quest/m3/README.md index d20f011e1a4..d6876dd4315 100644 --- a/quest/m3/README.md +++ b/quest/m3/README.md @@ -5,8 +5,8 @@ Work that follows the next breaking release and has someone waiting on it: byte streams and the mesh libraries first, then release execution after the cut, quests a named consumer needs, including downstream deployments, and bug fixes in -shipped code. Breaking and additive work mix here; the cut after m2's sorts -them by kind. +shipped code. Additive, API, and wire work mix here; the cut after m2's sorts +them by kind into m1, m2, and m3. ## Plan diff --git a/quest/m3/release/api-review.md b/quest/m3/release/api-review.md index 90b543a53c5..46161e05969 100644 --- a/quest/m3/release/api-review.md +++ b/quest/m3/release/api-review.md @@ -8,9 +8,10 @@ the maintainer approves is a quest that lands before the cut. ## Plan -Recurs once per major release (decided 2026-10-19). The [release -cut](/quest/m3/release/cut.md) re-creates this quest for the next release when -it shifts the milestones, so the PR finishing this run adds no successor. +Recurs once per API or wire cut (decided 2026-10-19; per breaking cut +2026-11-09). The [release cut](/quest/m3/release/cut.md) re-creates this quest +when the maintainer names the next API or wire cut, so the PR finishing this +run adds no successor. Record what this run learned (inventory method, findings, what to check first) in the cut's PR notes or a follow-up quest, so the next run starts from it. Only `/quest-delete` ends the recurrence. diff --git a/quest/m3/release/cut.md b/quest/m3/release/cut.md index 042eb7e03fe..d963581a6c6 100644 --- a/quest/m3/release/cut.md +++ b/quest/m3/release/cut.md @@ -11,8 +11,8 @@ Follow RELEASE.md's release procedure: merge release into main first, then main into release using merge commits. Confirm the maintainer's cut instruction before executing it. Right after merging release into main, set every eligible package with `just version 0.22.0` for this cut, then one -minor up per cut, following [Versions](/RELEASE.md#versions), including -packages that did not change. `@moq/qmux` and the Rust `qmux` crate are +minor up per later API or wire cut, following +[Versions](/RELEASE.md#versions), including packages that did not change. `@moq/qmux` and the Rust `qmux` crate are exempt from that version (`version.json`), so check each against its registry by hand: npm already has `@moq/qmux` 0.3.3 and 0.3.4, published from moq-dev/web-transport, while `js/qmux` is at 0.3.3. Publishing 0.3.3 @@ -51,22 +51,49 @@ cached groups on drafts 14 to 22. ✅ No backport (maintainer, 2026-11-04; [moq-dev/moq#7815](https://github.com/moq-dev/moq/pull/7815)), so check both fixes reach release. -Recurs once per major release (decided 2026-10-19; shift rule replaced -2026-11-05). The PR that finishes the cut shifts the milestones, as the root -[questline](/quest/README.md) describes: this epic's remaining publication -and adoption quests move to m0, m3's other quests split by kind into m1 -(additive) and m2 (breaking), m4's move to m3, m5 stays, and every link to a -moved path is rewritten. A recurring cut-gate child that its last run -re-created in m3, such as the [vendor -sync](/quest/m3/vendor-sync/README.md), moves under the re-created -gate instead. That PR also removes this path from every `Required`, which -releases the audits waiting on it. It then re-creates the cut gate at `quest/m2/cut-gate/README.md` from -the template below, and -this quest, the [API shape review](/quest/m3/release/api-review.md), the -[feature review](/quest/m3/release/feature-review.md), and the [Cargo feature -review](/quest/m3/release/feature-flags.md) at the same paths under a fresh -release epic in m3. Each keeps its Goal and recurrence paragraph and requires -the new `/quest/m2/README.md`, and the cut also requires all three reviews. +Recurs once per cut (decided 2026-10-19 as once per major release; per cut, +in three kinds, 2026-11-09). The kinds, what each publishes, and which checks +each runs are in [Releases](/RELEASE.md#releases). This run is the +`0.22.0` cut: it still waits on all of m2. Once it merges into `release` and +release-plz has published every package it bumps (the API diff's baselines), a +PR on `main` sets `phase` in `version.json` to `additive` (the cut PR keeps +the old phase, so its API diff only reports its breaks) and performs the re-split the root +[questline](/quest/README.md) describes. This epic's remaining publication and +adoption quests move to a release epic in m0, m3's other quests sort by kind +into m1 (additive), m2 (API breaks) and m3 (wire changes), m4 stays, m5 moves +to m6 and m5 starts empty, each milestone README's Goal is rewritten for its +new role, and each audit's recurrence names m4 instead of m3. + +Every cut's PR removes this path from every `Required`, which releases the +audits waiting on it, rewrites every link to a moved path, and re-creates this +quest as `/quest/m0/release/cut.md`, in m0's release epic (created if the +cut moved nothing there), keeping its Goal and this paragraph, with no `Required` and a `## Waiting` item for the +maintainer's instruction naming the next cut and its kind. Each later run +follows that kind: + +- **Additive**: the readiness checks, with the API diff refusing any break. + Changed JS packages and binding wrappers take patch bumps on `main` first; + release-plz proposes the Rust patches. +- **API or wire**: first re-create the [API shape + review](/quest/m3/release/api-review.md), the [feature + review](/quest/m3/release/feature-review.md), the [Cargo feature + review](/quest/m3/release/feature-flags.md), and the [migration + audit](/quest/m3/release/migrate-audit.md) beside it in m0's release + epic, each keeping + its Goal and recurrence paragraph, scoped to what changed since the last + breaking cut and requiring nothing, and add them to this quest's + `Required`. Then advance the shared minor with `just version`. +- **Wire**, which ends the cycle: also require `/quest/m2/README.md` and + `/quest/m3/README.md`, which the cut can wait on because it lives in m0, + not m3; finalize the cycle's wire version, then, once it merges + into `release` and its packages are published, set `phase` back to `additive` on `main`, and shift the milestones: remaining publication and adoption + quests to m0, m4's quests by kind into m1, m2 and m3, m5's to m4, and m6 + stays the deferred bucket. + +The `0.22.0` cut and each wire cut also re-create the cut gate in m3 from the +template below; a recurring cut-gate child that the last run re-created in +the later-work milestone, such as the [vendor +sync](/quest/m3/vendor-sync/README.md), moves under it. Only `/quest-delete` ends the recurrence. From the 2026-10-25 pre-cut run: @@ -85,16 +112,17 @@ merged moq-e2ee and moq-sign into moq-crypto (decided 2026-11-02, no yank): `release` branch release-plz proposal that bumps it. Cut gate template (moved here 2026-11-09 from the gate's own Plan; see the -decision below). The gate is an epic in m2 for the checks the cut needs that +decision below). The gate is an epic in m3 for the checks the cut needs that break nothing: `main` is no slower than `release`, vendored code has the upstream fixes it needs, and the hand-written `moq-c` is at parity with moq-ffi. It has no work of its own and completes when every child merges. It -recurs once per release cycle, always in m2, and never re-creates itself: m2 -holds it and the cut requires m2, so a copy made before the cut would block -that cut forever. Re-create its README with that Goal and this recurrence, a -fresh "main is no slower than release" child with its Goal and no +recurs once per release cycle, always in m3, and never re-creates itself: m3 +holds it and the cycle's wire cut requires m3, so a copy made before that cut +would block it forever. Cuts earlier in the cycle do not wait on it, but each +confirms on its candidate that the gate's finished checks still hold. +Re-create its README with that Goal and this recurrence, a fresh "main is no slower than release" child with its Goal and no measurements yet, and the [vendor sync](/quest/m3/vendor-sync/README.md) -questline that the last run re-created in m3. Only `/quest-delete` ends the +questline that the last run re-created in the later-work milestone. Only `/quest-delete` ends the recurrence. Decided 2026-11-09 (maintainer, /quest-unblock): the cut, not the gate, @@ -139,5 +167,4 @@ with the suites above. - [API shape review](/quest/m3/release/api-review.md) - every new or changed public API was reviewed for a better shape, and approved changes landed - [Feature review](/quest/m3/release/feature-review.md) - every major work line since the last release was judged end to end, and its follow-ups landed - [Cargo feature review](/quest/m3/release/feature-flags.md) - every Cargo feature was judged against the feature rules, and approved changes landed -- [Cycle phases](/quest/m3/release/cycle-phases.md) - the shift this cut performs sorts by additive, API and wire, and its recurrence is rewritten to match - [Claim new npm names](/quest/m3/release/npm-first-publish.md) - trusted publishing can publish every new `@moq/*` package diff --git a/quest/m3/release/cycle-phases.md b/quest/m3/release/cycle-phases.md deleted file mode 100644 index 7629c83185a..00000000000 --- a/quest/m3/release/cycle-phases.md +++ /dev/null @@ -1,73 +0,0 @@ -# [M] A cycle runs in phases by kind, cut on demand - -## Goal - -After the next cut, each release cycle runs in three phases by kind of -change: additive work, then API breaks, then wire changes. `main` can be cut -to `release` on demand at any point in the first two phases. The wire phase -is short, because `main` cannot be cut while a wire version is half changed. -A cut made while the cycle is still additive publishes patch versions; -every cut that carries an API break or a wire change advances the shared -minor, so a wire cut after an API cut advances it again. The questline, `RELEASE.md`'s Releases and Versions, the version -check, and the cut's recurrence all say so. - -## Plan - -Decided 2026-11-09 (maintainer, `/quest-plan`): - -- **Cadence.** ✅ Cuts on demand, in phases by kind (rejected: a weekly, - two-weekly or monthly schedule). -- **Wire work.** ✅ A short wire phase at the end of each cycle (rejected: - an unfinished wire version that is opt-in and carries a revision in its - name, so `main` is always cuttable; wire work on a branch until final). -- **Versions.** ✅ Patches while the cycle is additive (rejected: a shared - minor per cut, today's rule; one shared minor per cycle, holding API - breaks until the wire phase ends). -- **The next cut is unchanged.** ✅ It still waits on all of m2 (rejected: - cutting once no break is half-landed). - -Why: a cut that waits for every breaking change grows large. On 2026-11-09 -`main` was 3,190 commits ahead of `release`, and a deployment that follows -`release` can only take that whole. A wire change is the kind a deployed -peer must adapt to while a cluster is part-way through an upgrade, so it is -the riskiest to roll out and the one that stops `main` from being cut. -Keeping wire changes few and last leaves most of a cycle cuttable. - -Guidance: - -- The milestones follow the phases: m1 additive, m2 API breaks, m3 wire - changes, with today's later-work milestones moving down one. An API break - is what a published consumer adapts to when it rebuilds: the public Rust, - JS and bindings API, CLI flags, config keys and environment variables. A - wire change is what a deployed peer adapts to without rebuilding: a frozen - wire version. Decide where the hang catalog JSON and stored or exported - container formats fall; they read like wire, since a deployed peer parses - them. Urgent work of any kind still joins m0. -- The cut's shift performs the re-split, so the - [release cut](/quest/m3/release/cut.md) requires this quest and its - recurrence is rewritten here: it sorts into three kinds, not two, and it - recurs per cut rather than per major release. -- Decide what holds a phase's order. A break that lands on `main` during the - additive phase turns the next cut into a breaking one. Ordering the - milestones through `Required` keeps `quest unblocked` from offering the - work early, but nothing on a PR into `main` refuses a break today: - `just api-diff` runs only on PRs into `release`, and the cut only reports. - Choose the enforcement, such as an api-diff job with `--deny` on PRs into - `main` during the additive phase, or a label or `version.json` check. -- A cut in the additive phase has no break to audit: it needs the - [release cut](/quest/m3/release/cut.md)'s readiness checks but not the migration - audit or the API, feature and Cargo feature reviews. Say which checks each - kind of cut runs. -- `just version` and `version.json` enforce one shared minor advanced at - every breaking cut, API or wire. An additive cut skips the bump and lets release-plz propose - patches. Decide how the JS packages and the bindings take a patch at an - additive cut. -- After any publish, `just test wire-compat --remeasure` still lands the - refreshed planned breaks. - -Public API: none. Wire: none. The published version numbers change shape: -fewer shared minors, more patches. - -## Related - -- [Release cut](/quest/m3/release/cut.md) - performs the shift this quest redefines diff --git a/quest/m3/release/feature-flags.md b/quest/m3/release/feature-flags.md index 1ff46e89bfd..368ab8c8230 100644 --- a/quest/m3/release/feature-flags.md +++ b/quest/m3/release/feature-flags.md @@ -13,9 +13,10 @@ quest that lands before the cut. ## Plan -Recurs once per major release (decided 2026-10-26). The [release -cut](/quest/m3/release/cut.md) re-creates this quest for the next release when -it shifts the milestones, so the PR finishing this run adds no successor. +Recurs once per API or wire cut (decided 2026-10-26; per breaking cut +2026-11-09). The [release cut](/quest/m3/release/cut.md) re-creates this quest +when the maintainer names the next API or wire cut, so the PR finishing this +run adds no successor. Record what this run learned (inventory method, findings, what to check first) in the cut's PR notes or a follow-up quest, so the next run starts from it. Only `/quest-delete` ends the recurrence. diff --git a/quest/m3/release/feature-review.md b/quest/m3/release/feature-review.md index 3340a5cec2a..ec499473508 100644 --- a/quest/m3/release/feature-review.md +++ b/quest/m3/release/feature-review.md @@ -10,9 +10,10 @@ the cut, or a recorded decision to ship it as is. ## Plan -Recurs once per major release (decided 2026-10-19). The [release -cut](/quest/m3/release/cut.md) re-creates this quest for the next release when -it shifts the milestones, so the PR finishing this run adds no successor. +Recurs once per API or wire cut (decided 2026-10-19; per breaking cut +2026-11-09). The [release cut](/quest/m3/release/cut.md) re-creates this quest +when the maintainer names the next API or wire cut, so the PR finishing this +run adds no successor. Record what this run learned (inventory method, findings, what to check first) in the cut's PR notes or a follow-up quest, so the next run starts from it. Only `/quest-delete` ends the recurrence. diff --git a/quest/m3/release/migrate-audit.md b/quest/m3/release/migrate-audit.md index 3022102d88d..80edb54d887 100644 --- a/quest/m3/release/migrate-audit.md +++ b/quest/m3/release/migrate-audit.md @@ -9,6 +9,11 @@ published version. ## Plan +Recurs once per API or wire cut (decided 2026-11-09). The [release +cut](/quest/m3/release/cut.md) re-creates this quest when the maintainer +names the next API or wire cut, so the PR finishing this run adds no +successor. Only `/quest-delete` ends the recurrence. + Decided 2026-10-16 (maintainer interview); the diff tooling moved to its own m1 quest on 2026-10-22. diff --git a/sh/api-diff/run.sh b/sh/api-diff/run.sh index 93ce238356d..1bcc0d4e641 100755 --- a/sh/api-diff/run.sh +++ b/sh/api-diff/run.sh @@ -54,7 +54,8 @@ row() { # Whether a full-context diff on stdin breaks the baseline: it removes a line, # which includes changing one, or adds a line inside a declaration the baseline # has, such as a required field on an input interface or a C struct, since a line -# diff cannot tell which of those break callers. A line's declaration is the +# diff cannot tell which of those break callers, except an optional TypeScript +# property (`name?: T`), which no caller must pass. A line's declaration is the # nearest line above it indented less, so only whole new declarations are # additions. breaks() { @@ -65,8 +66,12 @@ breaks() { line ~ /^[[:space:]]*$/ { next } { match(line, /^[[:space:]]*/) - while (depth && indent[depth] >= RLENGTH) depth-- - if (mark == "+" && depth && parent[depth] == " ") { broke = 1; exit } + sibling = "" + while (depth && indent[depth] >= RLENGTH) { if (indent[depth] == RLENGTH) sibling = parent[depth]; depth-- } + optional = line ~ /^[[:space:]]*(readonly[[:space:]]+)?[A-Za-z_$][A-Za-z0-9_$]*\?:/ + # A closing bracket ends the added line it lines up with, such as an optional property'"'"'s inline object type. + closes = sibling == "+" && line ~ /^[[:space:]]*[]})]/ + if (mark == "+" && depth && parent[depth] == " " && !optional && !closes) { broke = 1; exit } indent[++depth] = RLENGTH parent[depth] = mark } diff --git a/sh/version.py b/sh/version.py index 2fd71579905..1bbeea0661e 100644 --- a/sh/version.py +++ b/sh/version.py @@ -169,7 +169,13 @@ def lock_version(root, package): return matches[0][1] +# The release cycle's phase, which the API diff reads: `additive` denies breaks. +PHASES = (None, "additive", "api", "wire") + + def check(root, config): + if config["phase"] not in PHASES: + raise ValueError(f"invalid phase {config['phase']!r}: expected one of {PHASES}") minor = config["minor"] if minor is None: print("shared version: disabled until the release cut runs just version") diff --git a/sh/version.test.py b/sh/version.test.py index efb56579f1e..72b72ccec26 100644 --- a/sh/version.test.py +++ b/sh/version.test.py @@ -28,7 +28,7 @@ def setUp(self): self.addCleanup(self.temp.cleanup) self.root = Path(self.temp.name) self.env = dict(os.environ, CARGO_NET_OFFLINE="true", GIT_CONFIG_GLOBAL=os.devnull, GIT_CONFIG_NOSYSTEM="1") - self.config = {"minor": None, "exemptions": {"rust": ["independent"], "npm": ["@moq/qmux"]}} + self.config = {"minor": None, "phase": None, "exemptions": {"rust": ["independent"], "npm": ["@moq/qmux"]}} self.write("version.json", json.dumps(self.config)) self.write("Cargo.toml", '[workspace]\nmembers = ["rs/*"]\nresolver = "2"\n') self.crate( @@ -135,6 +135,12 @@ def test_disabled_before_cut_and_invalid_marker_fails(self): for value in ("", "0.22.0", "0.0", "0.022"): self.write("version.json", json.dumps({**self.config, "minor": value})) self.assertNotEqual(self.check(ok=False).returncode, 0) + for value in ("additive", "api", "wire"): + self.write("version.json", json.dumps({**self.config, "phase": value})) + self.assertIn("disabled", self.check().stdout) + for value in ("", "Additive", "breaking"): + self.write("version.json", json.dumps({**self.config, "phase": value})) + self.assertNotEqual(self.check(ok=False).returncode, 0) def test_cut_promotes_only_published_library_dependencies_and_preserves_exemptions(self): before = self.snapshot() diff --git a/version.json b/version.json index 89cb82f17ef..8a502c47e2a 100644 --- a/version.json +++ b/version.json @@ -1,5 +1,6 @@ { "minor": null, + "phase": null, "exemptions": { "rust": ["kio", "kio-macros", "qmux"], "npm": ["@moq/qmux"]