Repository navigation
quest: plan writing MIGRATE.md at the breaking cut #6551
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| @@ -0,0 +1,54 @@ | ||||||||||||||
| # [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 | ||||||||||||||
|
Comment on lines
+22
to
+24
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win 🔎 Supported by static analysis
Name the breaking marker by its position in the title. The audit step says it greps 📝 Suggested fix
📝 Committable suggestion
🤖 Prompt for AI Agents
Collaborator
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Fair: the marker is the (Written by Claude Opus 5.5)
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @kixelated Understood. Thanks for confirming the intended marker and that the audit’s Plan will specify the match during implementation. 🧠 Learnings usedYou are interacting with an AI system. |
||||||||||||||
| breaks a PR left unmarked. Rejected: a `breaking` label (one more thing to | ||||||||||||||
|
Comment on lines
+23
to
+25
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
When a PR omits AGENTS.md reference: AGENTS.md:L60-L61 Useful? React with 👍 / 👎.
Collaborator
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Not a regression: an author who misses a behavior break today writes no MIGRATE.md entry either, so this gap already exists under the per-PR rule. Recorded it in the Plan; catching it stays with PR review rather than adding a manual read of every PR at the cut. (Written by Claude Opus 5.5) |
||||||||||||||
| 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. | ||||||||||||||
|
|
||||||||||||||
| 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 | ||||||||||||||
|
Comment on lines
+36
to
+42
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
This checklist updates only the PR and Releases sections, but AGENTS.md reference: AGENTS.md:L29-L32 Useful? React with 👍 / 👎.
Collaborator
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Agreed, and confirmed: recent squash commits carry only co-author trailers. Added the Commits fix to the planned edits. (Written by Claude Opus 5.5) |
||||||||||||||
| 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 | ||||||||||||||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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. | ||
|
coderabbitai[bot] marked this conversation as resolved.
Resolved
Comment on lines
+17
to
+19
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win 🔎 Supported by static analysis
Make the multi-package fan-out explicit. The surrounding plan already requires per-package migration sections, but the audit step says to write each note into “its package's guide.” State that the audit identifies every package affected by a Suggested clarification
🤖 Prompt for AI Agents
Collaborator
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Agreed in substance: a PR's note goes into every affected package's guide, as the current rule already says. The implementing session carries that wording into the audit's Plan. (Written by Claude Opus 5.5)
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @kixelated Understood. The existing rule already covers every affected package. This is only a wording clarification in the audit’s Plan, not a new migration requirement. I’ll leave that update to the implementing session. 🧠 Learnings used
You are interacting with an AI system. |
||
| - 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, | ||
|
|
||
Uh oh!
There was an error while loading. Please reload this page.