From d157c59b7e89e665f3f20fb0eb4d585adbbb4731 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 10 Nov 2026 17:33:15 -0800 Subject: [PATCH 1/9] chore(quest): claim quest/m3/release/cycle-phases.md Quest-Claim: b8cc42eb83d24471 From 419796607210f12a9befd9c4c1f6581581d4fe34 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 10 Nov 2026 17:41:26 -0800 Subject: [PATCH 2/9] wip --- .github/workflows/api-diff.yml | 43 +++++++++++++----- .github/workflows/nightly.yml | 6 +++ CONTRIBUTING.md | 26 +++++++++-- quest/README.md | 40 +++++++++++++--- quest/m3/README.md | 4 +- quest/m3/release/README.md | 1 - quest/m3/release/api-review.md | 7 +-- quest/m3/release/cut.md | 66 ++++++++++++++++++--------- quest/m3/release/cycle-phases.md | 73 ------------------------------ quest/m3/release/feature-flags.md | 7 +-- quest/m3/release/feature-review.md | 7 +-- quest/m3/release/migrate-audit.md | 5 ++ sh/version.py | 6 +++ sh/version.test.py | 8 +++- version.json | 1 + 15 files changed, 169 insertions(+), 131 deletions(-) delete mode 100644 quest/m3/release/cycle-phases.md diff --git a/.github/workflows/api-diff.yml b/.github/workflows/api-diff.yml index f72902cac22..c1a17da3b93 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 @@ -24,24 +26,43 @@ jobs: - 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 }} + # Unquoted on purpose: the report-only mode passes no argument. + run: nix develop --command just api-diff $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 d8ed5cbd0cc..ebb0715ec68 100644 --- a/.github/workflows/nightly.yml +++ b/.github/workflows/nightly.yml @@ -84,6 +84,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 CONTRIBUTING.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/CONTRIBUTING.md b/CONTRIBUTING.md index 1b0f30b8301..c1649e4d117 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -98,19 +98,32 @@ For an advisory against Quinn, follow the advisory triage in [`rs/moq-quic/READM `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`; the `0.22.0` cut, and after it the wire cut that ends each cycle, sets it to `additive`. +`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. + +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. + - 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. - 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. # 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`. @@ -128,7 +141,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 44d4a25ff1e..fa911fa9ef6 100644 --- a/quest/README.md +++ b/quest/README.md @@ -34,13 +34,39 @@ 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](/CONTRIBUTING.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 m0 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 5ba40b1d8ee..13e7b7d6649 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/README.md b/quest/m3/release/README.md index 0bc42fcdbec..0accc575b42 100644 --- a/quest/m3/release/README.md +++ b/quest/m3/release/README.md @@ -32,7 +32,6 @@ production stability proven merely because upstream artifacts published. - [Feature review](/quest/m3/release/feature-review.md) - every major work line since the last release judged end to end before the cut - [Cargo feature review](/quest/m3/release/feature-flags.md) - defaults stay lean and every remaining feature is scoped to the crate that owns it, before the cut - [Claim new npm names](/quest/m3/release/npm-first-publish.md) - a maintainer claims `@moq/clock`, `libav`, and `video` on npm with trusted publishing, before the cut publishes them -- [Cycle phases](/quest/m3/release/cycle-phases.md) - later cycles run additive, API, then wire, and cut on demand - [Cut and publish](/quest/m3/release/cut.md) - independently executable after m2; release-triggered publication - [Published assets](/quest/m3/release/assets-release.md) - npm carries hostable worklets - [C++ publication](/quest/m3/release/cpp-release.md) - archives and matching OBS plugin publish and install 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 4d2bb737943..850899f37d0 100644 --- a/quest/m3/release/cut.md +++ b/quest/m3/release/cut.md @@ -11,7 +11,7 @@ Follow CONTRIBUTING.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](/CONTRIBUTING.md#versions), including +minor up per later API or wire cut, following [Versions](/CONTRIBUTING.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 @@ -51,22 +51,44 @@ 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](/CONTRIBUTING.md#releases). This run is the +`0.22.0` cut: it still waits on all of m2, and its PR sets `phase` in +`version.json` to `additive` and performs the re-split the root +[questline](/quest/README.md) describes. This epic's remaining publication and +adoption quests move to 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, 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 at the same path under a fresh release epic in m3, 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) at the same paths, 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`, finalize the cycle's wire version, set `phase` back + to `additive`, 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,13 +107,14 @@ 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 +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 @@ -139,5 +162,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 cbded919302..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, `CONTRIBUTING.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 9ce916465bf..4f1689330fe 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 81cd5507de3..2232ee23519 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/version.py b/sh/version.py index 0cf2adae937..29547f8f137 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"] From 4e26c0edc9836599ce1f7cab90112efa894f70fb Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 10 Nov 2026 17:41:53 -0800 Subject: [PATCH 3/9] wip: shellcheck --- .github/workflows/api-diff.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/api-diff.yml b/.github/workflows/api-diff.yml index c1a17da3b93..ef9d15460af 100644 --- a/.github/workflows/api-diff.yml +++ b/.github/workflows/api-diff.yml @@ -59,8 +59,8 @@ jobs: - name: Diff against the last release id: diff if: ${{ !steps.mode.outputs.skip }} - # Unquoted on purpose: the report-only mode passes no argument. - run: nix develop --command just api-diff $ARGS + # The report-only mode passes no argument. + run: nix develop --command just api-diff ${ARGS:+"$ARGS"} env: ARGS: ${{ steps.mode.outputs.args }} # Lists and downloads the moq-c and moq-ffi release assets. From a7e711ecf35bc7c401904b52ba0fbaf610dd136a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 10 Nov 2026 17:44:49 -0800 Subject: [PATCH 4/9] wip: layout --- CONTRIBUTING.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c1649e4d117..96982ecd16e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -105,19 +105,19 @@ The maintainer opens the next phase with a PR that changes `phase`; the `0.22.0` `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. -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. - - 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 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 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 From fa3c02db9e8dfdc523616b0550ce2c97faeb6f9b Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 10 Nov 2026 17:47:57 -0800 Subject: [PATCH 5/9] quest: release cycles run in phases by kind, cut on demand Co-Authored-By: Claude Opus 5.5 --- quest/m3/release/cut.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/quest/m3/release/cut.md b/quest/m3/release/cut.md index 850899f37d0..388f8050d51 100644 --- a/quest/m3/release/cut.md +++ b/quest/m3/release/cut.md @@ -11,8 +11,8 @@ Follow CONTRIBUTING.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 later API or wire cut, following [Versions](/CONTRIBUTING.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](/CONTRIBUTING.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 @@ -114,10 +114,10 @@ moq-ffi. It has no work of its own and completes when every child merges. It 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 +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, From 6afedec5cca070f8417faafc081d07f2c0b04fa8 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 12 Nov 2026 14:09:17 -0800 Subject: [PATCH 6/9] quest: reset the phase on main after a breaking cut merges, so the cut's API diff only reports Co-Authored-By: Claude Opus 5.5 --- RELEASE.md | 2 +- quest/m3/release/cut.md | 9 +++++---- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index 6cdc9670174..8d4099eed4f 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -5,7 +5,7 @@ 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`; the `0.22.0` cut, and after it the wire cut that ends each cycle, sets it to `additive`. +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`: the cut PR itself carries breaks, so its API diff must only report. `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. diff --git a/quest/m3/release/cut.md b/quest/m3/release/cut.md index 5b6ecc3a9a6..a1551baf611 100644 --- a/quest/m3/release/cut.md +++ b/quest/m3/release/cut.md @@ -54,8 +54,9 @@ both fixes reach release. 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, and its PR sets `phase` in -`version.json` to `additive` and performs the re-split the root +`0.22.0` cut: it still waits on all of m2. Once it merges into `release`, 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 @@ -83,8 +84,8 @@ follows that kind: `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, set `phase` back - to `additive`, and shift the milestones: remaining publication and adoption + not m3; finalize the cycle's wire version, then, once it merges + into `release`, 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. From 8c562055acd3ef257ef145f4b9da11bd051afdd2 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 12 Nov 2026 14:39:57 -0800 Subject: [PATCH 7/9] quest: reset the phase only after the cut's packages publish, since they are the API diff's baselines Co-Authored-By: Claude Opus 5.5 --- RELEASE.md | 2 +- quest/m3/release/cut.md | 5 +++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index 8d4099eed4f..9799a1e7e05 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -5,7 +5,7 @@ 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`: the cut PR itself carries breaks, so its API diff must only report. +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. diff --git a/quest/m3/release/cut.md b/quest/m3/release/cut.md index a1551baf611..d963581a6c6 100644 --- a/quest/m3/release/cut.md +++ b/quest/m3/release/cut.md @@ -54,7 +54,8 @@ both fixes reach release. 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`, a +`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 @@ -85,7 +86,7 @@ follows that kind: - **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`, set `phase` back to `additive` on `main`, and shift the milestones: remaining publication and adoption + 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. From 6ba86ff9f15c66fb08cc75131841ced89ed88441 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 12 Nov 2026 14:42:41 -0800 Subject: [PATCH 8/9] api-diff: an optional TS property is an addition, and Nightly's main run gets the cache-write environment Co-Authored-By: Claude Opus 5.5 --- .github/workflows/api-diff.yml | 2 ++ sh/api-diff/run.sh | 6 ++++-- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/.github/workflows/api-diff.yml b/.github/workflows/api-diff.yml index ef9d15460af..a318c46c9cd 100644 --- a/.github/workflows/api-diff.yml +++ b/.github/workflows/api-diff.yml @@ -20,6 +20,8 @@ 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: diff --git a/sh/api-diff/run.sh b/sh/api-diff/run.sh index 93ce238356d..bf36abbd6c2 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() { @@ -66,7 +67,8 @@ breaks() { { match(line, /^[[:space:]]*/) while (depth && indent[depth] >= RLENGTH) depth-- - if (mark == "+" && depth && parent[depth] == " ") { broke = 1; exit } + optional = line ~ /^[[:space:]]*(readonly[[:space:]]+)?[A-Za-z_$][A-Za-z0-9_$]*\?:/ + if (mark == "+" && depth && parent[depth] == " " && !optional) { broke = 1; exit } indent[++depth] = RLENGTH parent[depth] = mark } From c77ecb37a8a9310cef13898ad04c616be767316a Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 12 Nov 2026 14:43:37 -0800 Subject: [PATCH 9/9] api-diff: a closing bracket belongs to the added property it lines up with Co-Authored-By: Claude Opus 5.5 --- sh/api-diff/run.sh | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/sh/api-diff/run.sh b/sh/api-diff/run.sh index bf36abbd6c2..1bcc0d4e641 100755 --- a/sh/api-diff/run.sh +++ b/sh/api-diff/run.sh @@ -66,9 +66,12 @@ breaks() { line ~ /^[[:space:]]*$/ { next } { match(line, /^[[:space:]]*/) - while (depth && indent[depth] >= RLENGTH) depth-- + 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_$]*\?:/ - if (mark == "+" && depth && parent[depth] == " " && !optional) { broke = 1; exit } + # 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 }