From 6798e161e8505a1e9e6e1f9267d0149cf793462c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 23 Oct 2026 08:25:59 -0700 Subject: [PATCH 1/2] quest: plan writing MIGRATE.md at the breaking cut Co-Authored-By: Claude Opus 5.5 --- quest/m0/README.md | 1 + quest/m0/migrate-at-cut.md | 48 +++++++++++++++++++++++++++++++ quest/m2/release/migrate-audit.md | 5 ++++ 3 files changed, 54 insertions(+) create mode 100644 quest/m0/migrate-at-cut.md diff --git a/quest/m0/README.md b/quest/m0/README.md index 4258edd6ed6..af95677dd6b 100644 --- a/quest/m0/README.md +++ b/quest/m0/README.md @@ -46,4 +46,5 @@ Each lands its fixes in its own PR and plans only what needs a decision. - [Release shutdown backport](/quest/m0/ffi-shutdown-backport.md) - `release` publishes a non-breaking moq-ffi with an async `drain()` and qmux sessions on the QUIC stream limit - [Release fixed delay](/quest/m0/release-fixed-delay.md) - a fixed latency on `release`, which moq.dev runs, ignores the catalog's jitter and delay as `main` already does - [CI cost and latency](/quest/m0/ci/README.md) - cloud CI runs only in the merge queue as one `just ci` pass, expensive checks run nightly and gate `release`, caches move to R2, and runners are chosen last +- [MIGRATE.md at the cut](/quest/m0/migrate-at-cut.md) - PRs stop conflicting on `MIGRATE.md`: breaking PRs carry their migration note in the PR, and the breaking cut writes the guides - [Lint override and deprecation audit](/quest/m0/audit-lints.md) - every lint suppression is still needed and says why, nothing calls a deprecated API, and stale Rust overrides fail the build diff --git a/quest/m0/migrate-at-cut.md b/quest/m0/migrate-at-cut.md new file mode 100644 index 00000000000..11583e22045 --- /dev/null +++ b/quest/m0/migrate-at-cut.md @@ -0,0 +1,48 @@ +# [S] Write MIGRATE.md at the breaking cut + +## Goal + +PRs into `main` no longer touch `MIGRATE.md`, so they stop conflicting on it, +while each breaking cut still ships a correct per-package migration guide +stating the net change from the last published version. The guide format +readers see is unchanged. + +## Plan + +Decided 2026-10-23 (maintainer interview): + +- Conflicts come from every breaking PR inserting at the top of the same + `## Unreleased` section. Notes are written once, at the cut, instead of per + PR. Rejected: per-PR fragment files stitched at the cut (more files plus a + stitch recipe) and a `merge=union` driver (GitHub's PR and merge-queue + merges ignore it, so it only helps local merges). +- A breaking PR keeps the conventional `!` in its title, which becomes the + squash subject, and says how to migrate in its Impact bullet. Squash + commits drop the PR body, so the + [migration audit](/quest/m2/release/migrate-audit.md) greps `git log` for + `!` subjects since the `release` merge base, reads each PR's Impact + section, and relies on the [API-diff check](/quest/m1/api-diff.md) for + breaks a PR left unmarked. Rejected: a `breaking` label (one more thing to + remember) and reading every merged PR (hundreds per cycle). +- The `## Unreleased` entries already on `main` stay as the cut's starting + draft, and [moq-dev/moq#6443](https://github.com/moq-dev/moq/pull/6443) + lands as planned. + +Changes: + +- `AGENTS.md` Public API and `CONTRIBUTING.md` PRs: a breaking change marks + its title with `!` and its Impact bullet says how to migrate; drop the + per-PR `MIGRATE.md` entry rule. +- `CONTRIBUTING.md` Releases: replace the "rename `## Unreleased`" step with + the cut writing each changed package's version-transition section from the + audit. +- `doc/setup/upgrade.md` and `doc/lib/index.md`: say entries appear when a + breaking release is cut, not as changes land on `main`. +- Rewrite every quest that tells its PR to add a `MIGRATE.md` entry + (`rg -l MIGRATE quest`) to put the note in the PR's Impact bullet instead, + and update the migration audit's Plan to gather from `!` PRs. + +## Related + +- [Migration audit](/quest/m2/release/migrate-audit.md) - writes the entries this quest stops PRs from adding +- [MIGRATE matches release](/quest/m1/api-audit/migrate.md) - the in-flight alignment of today's entries diff --git a/quest/m2/release/migrate-audit.md b/quest/m2/release/migrate-audit.md index f908a6e6809..3ebaa534694 100644 --- a/quest/m2/release/migrate-audit.md +++ b/quest/m2/release/migrate-audit.md @@ -12,6 +12,11 @@ published version. Decided 2026-10-16 (maintainer interview); the diff tooling moved to its own m1 quest on 2026-10-22. +- PRs stop writing `MIGRATE.md` entries once + [MIGRATE.md at the cut](/quest/m0/migrate-at-cut.md) lands (decided + 2026-10-23): gather every `!` subject in `git log` since the `release` + merge base and write each PR's Impact-bullet migration note into its + package's guide. - Run the API-diff report on the cut PR and read the diff of the hand-written binding wrappers (`py/moq-rs`, `kt/moq`, `dart/moq`, `go/wrapper`, `swift`, `cpp/moq`, `cpp/obs`) and of each binary's flags, From 713d10cf0dab6c95c5c1123f9e5628346312dbfa Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 23 Oct 2026 08:31:53 -0700 Subject: [PATCH 2/2] quest: note the unmarked-break gap and the stale Commits claim Co-Authored-By: Claude Opus 5.5 --- quest/m0/migrate-at-cut.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/quest/m0/migrate-at-cut.md b/quest/m0/migrate-at-cut.md index 11583e22045..b374b340f7c 100644 --- a/quest/m0/migrate-at-cut.md +++ b/quest/m0/migrate-at-cut.md @@ -23,7 +23,10 @@ Decided 2026-10-23 (maintainer interview): `!` subjects since the `release` merge base, reads each PR's Impact section, and relies on the [API-diff check](/quest/m1/api-diff.md) for breaks a PR left unmarked. Rejected: a `breaking` label (one more thing to - remember) and reading every merged PR (hundreds per cycle). + remember) and reading every merged PR (hundreds per cycle). A behavior + break that keeps its declarations and lacks `!` escapes both; it escapes + today's per-PR rule the same way, since an author who misses a break + writes no entry either, so catching it stays with PR review. - The `## Unreleased` entries already on `main` stay as the cut's starting draft, and [moq-dev/moq#6443](https://github.com/moq-dev/moq/pull/6443) lands as planned. @@ -33,6 +36,9 @@ Changes: - `AGENTS.md` Public API and `CONTRIBUTING.md` PRs: a breaking change marks its title with `!` and its Impact bullet says how to migrate; drop the per-PR `MIGRATE.md` entry rule. +- `CONTRIBUTING.md` Commits: drop the claim that the PR description becomes + the squash commit's body; the merge queue keeps only the title and + co-author trailers. - `CONTRIBUTING.md` Releases: replace the "rename `## Unreleased`" step with the cut writing each changed package's version-transition section from the audit.