Trim the migration guide to genuine v1-to-v2 breaking changes - #3183
Trim the migration guide to genuine v1-to-v2 breaking changes#3183maxisbey wants to merge 1 commit into
Conversation
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
No issues found across 1 file
Not reviewed (too large): docs/migration.md (~2,117 lines) - if these are generated or fixture files, add them to ignored paths to exclude them from future reviews.
Tip: cubic can generate docs of your entire codebase and keep them up to date. Try it here.
Re-trigger cubic
📚 Documentation preview
|
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
Thanks for fixing the two dangling whats-new.md anchors from my earlier comment — commit 426de27 resolves that, and I found no new issues this run. Still deferring to a human for a final pass, since this is a large editorial rewrite of the migration guide whose behavioral claims (which v1 examples run, what was cut as non-migration content) can't be fully verified mechanically.
What was reviewed:
- Every cross-page link to
migration.md#...anchors (7 remaining) resolves against the trimmed headings; no other page links to a deleted section. - Every intra-document anchor in
migration.md(the "Find your changes" tables, suggested order, and inline cross-references) matches an existing heading slug. - Relative doc links check out; the two
api/targets are generated at build time permkdocs.yml.
Extended reasoning...
Overview
This PR is documentation-only: it trims docs/migration.md from 91 to 73 sections, removing entries that were changelog/deprecation notes rather than genuine v1-to-v2 breaking changes, correcting several before/after code blocks, and folding near-duplicate entries. It also drops two links from docs/whats-new.md whose target sections the trim removes — the exact issue a prior run of this review flagged, now resolved by commit 426de27.
Security risks
None. No code, configuration, or CI changes — only Markdown under docs/. The removed sections include some security-adjacent content (SEP-2243 header validation, credential binding), but removing documentation of shipped behavior does not change the behavior itself.
Level of scrutiny
Docs-only changes warrant moderate scrutiny: the failure mode is misleading migration guidance, not broken software. I mechanically verified everything verifiable — all cross-page and intra-document anchors resolve, no other docs page links to a deleted section, and relative links point at real (or build-generated) files. What cannot be verified mechanically is the content accuracy of the rewritten prose and code examples: the author states every surviving before/after block was executed against v1.x and main respectively, but I cannot reproduce that here, and the judgment calls about which entries count as "genuine migration content" (e.g. dropping the SEP-2352/SEP-2350 notes and the "Notes for 2026-era connections" group entirely) are editorial decisions a maintainer should sign off on.
Other factors
The prior review cycle worked as intended: the one concrete defect (dangling anchors) was reported inline and fixed in a follow-up commit before this run. The bug hunting system found nothing further. Given the size of the rewrite (~700 changed lines in migration.md) and the repository's own AGENTS.md emphasis on migration-guide accuracy for the v2 line, a human skim of the removed and rewritten sections is the remaining review work — hence deferral rather than approval.
426de27 to
d0dc9bd
Compare
The guide had accumulated entries that are not v1-to-v2 migration items: new v2 feature notes, "what did not change" reassurance sections, spec-adoption commentary, deprecations of APIs that still work, and internal fixes with nothing for a migrator to change. Remove those, including the whole Deprecations group; the two deprecation consequences a migrator does act on (warnings-as-errors test runs, and client calls that die on the default 2026-era connection) live in the testing section. Correct code and claims that were wrong for v1.x or stale for current 2.x, and verify every remaining before/after example against the v1.x and main trees. Two behavior changes that shipped in 2.1 without a guide entry get one: exception messages from tool handlers no longer reach the model unless raised as ToolError, and content-block return annotations no longer produce structured output. Reframe the 2026-era notes as behavior changes migrated code sees on v2's default connection, fold closely related entries together, standardize on the documented imports, regenerate the index and suggested-order blocks, and cut history and over-explanation throughout. Also drop two whats-new.md links whose target sections this removes. No-Verification-Needed: documentation-only change
d0dc9bd to
934a417
Compare
1 participant
Cuts
docs/migration.mddown to what it is for: someone with working v1.x code that breaks (or silently changes behavior) on v2, and needs to know what to write instead. Rebased onto currentmain(post-2.1.1) with every example re-verified against today'sv1.xandmain.Motivation and Context
The guide had drifted into a changelog: new-in-v2 feature notes, "what did not change" inventories, spec-adoption commentary, deprecations of APIs that still work, and internal fixes with nothing for a migrator to change, alongside stale before/after code and a fair amount of history narration. A porter (or an agent pointed at the page) had to sieve for the parts that apply.
What changed:
mcp dev/mcp installpinning note, the 4 MiB body limit (also on v1.x; kept as a clause besidemax_request_body_size), the resolver capability gate, thestdio_clientshutdown rework, SEP-2352/SEP-2350 adoption, lowlevel-handler registration through private attributes, thesubscribe-capability fix,client_secret_post/-32601wire notes, and theMcp-Param-*section. The two deprecation consequences a migrator does act on stay, under Testing utilities: warnings-as-errors suites failing onMCPDeprecationWarning, and the client calls that go dead on the default 2026-eraClient(server)connection (mode="legacy"restores them).mcp.typesis a permanent alias (imports keep working),issuer=on the client-credentials providers,session_idle_timeout/max_sessionsin the moved-parameters list,UnexpectedToolErroron directcall_tool(), the removedValidationError, PRM discovery failures, and more. Every remaining before/after block was executed or import-checked againstv1.xandmain.@mcp.tool()handlers no longer reach the model unless raised asToolError, and content-block return annotations no longer produceoutput_schema/structured_content.NoBackChannelError, log opt-in, listen-only change notifications), folded near-duplicates (dependency requirements, default server identity, direct calls toMCPServerprotocol methods, the in-memory testing helper), standardized imports, regenerated the index and suggested-order blocks, and cut history and over-explanation throughout.How Has This Been Tested?
Each surviving example was executed or import-checked against the corresponding tree (
v1.xfor "Before",mainfor "After"), driving handler code through the in-memory client where relevant.scripts/docs/build.sh(strict Zensical build, render-order and cross-reference checks) and markdownlint pass; every intra-document anchor resolves under both GitHub and Python-Markdown slug rules, and the headings other pages (and themcp.server.fastmcpshim message) link to are unchanged.Breaking Changes
None — documentation only.
Types of changes
Checklist
Additional context
Also touches
docs/whats-new.md, only to drop two links whose target sections this removes (mcp dev/mcp installpinning andMcp-Param-*); the strict build aborts on missing anchors.migration.mdis excluded from translation, but the translatedwhats-new.mdpages still carry those two links until the translation tool is next run (their builds are non-strict, so this is a warning, not a failure).AI Disclaimer