docs: restructure the migration guide around topical groups with a navigation layer#3058
Conversation
…vigation layer The v1-to-v2 migration guide had grown by accretion: one section per breaking PR, in merge order, under four coarse buckets. Restructure it so both a skimming human and a searching agent can find what applies to them: - Add a navigation layer: a symptom-keyed table of the changes almost every project hits, an area index, and a suggested migration order. - Group sections topically (packaging, types/wire, MCPServer, lowlevel Server, clients, transports, OAuth/server auth, validation and wire behavior, testing, deprecations), ordered the way a migration actually proceeds. - Drop sections that describe 2026-07-28 features rather than v1-to-v2 breaks (Mcp-Param client mirroring, cache hints, extensions API, identity assertion, modeled protocol fields, additive lowlevel app); that content lives in whats-new.md and the feature pages. The server-side Mcp-Param section stays, under a clearly scoped "Notes for 2026-era connections" heading, since whats-new.md links to it. - Merge three satellite sections into their parents and move behavior changes that were filed under "Bug Fixes"/"New Features" into the appropriate groups. - Add missing breaks found by a v1.28.1-vs-v2 surface audit: float timeouts replacing timedelta, the 408-to--32001 timeout error code, lowlevel tool-handler exceptions becoming JSON-RPC errors, streamable-HTTP non-2xx handling, the _meta envelope and OpenTelemetry dependencies, OAuth offline_access/prompt=consent and issuer validation, stricter token-endpoint client authentication, MCPServer constructor positional-slot changes, the default server name change, dependency floor bumps, and several smaller renames folded into existing sections. - Fix stale or wrong claims found while validating every section against both runtimes: model_dump() now needs by_alias=True for the wire shape, Before-examples that never worked in v1 as shown, the StatelessModeNotSupported reference (never in any v1 release), and the mcp.shared.context removal claims. Heading anchors that other pages deep-link (whats-new.md) are unchanged. mkdocs build --strict and markdownlint pass.
📚 Documentation preview
|
![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
Tip: cubic can generate docs of your entire codebase and keep them up to date. Try it here.
Re-trigger cubic
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
Docs-only change and the claims I spot-checked against the codebase (default server name, REQUEST_TIMEOUT code, version constants) hold up, but this is a full restructure of the migration guide that also removes and reclassifies content, so the editorial scope decisions deserve a maintainer's look.
Extended reasoning...
Overview
This PR touches a single file, docs/migration.md, rewriting essentially the whole page: a new navigation layer (symptom table, audience index, migration order), topical regrouping of existing sections, removal of sections judged to be 2026-era-only, reclassification of entries previously filed under Bug Fixes / New Features, and a substantial amount of newly written content documenting breaks that were previously undocumented (timeout types, error-code changes, OAuth behavior changes, constructor positional-slot changes, etc.).
Security risks
None. No source code, configuration, CI, or dependency changes — documentation only.
Level of scrutiny
Low from a code-safety standpoint, but the migration guide is the primary user-facing document for the v2 upgrade, and this PR both adds many specific behavioral claims and deletes existing sections under a new inclusion rule ("only changes observable to migrated v1 code against 2025-11-25 peers"). Whether that scoping rule and the removals are the right editorial call is a maintainer decision, not something I can verify mechanically. I spot-checked several factual claims against the current tree (default server name 'mcp-server', REQUEST_TIMEOUT = -32001 in mcp_types, LATEST_HANDSHAKE_VERSION exports) and they are accurate, and the author reports validating every section against both runtimes plus a passing mkdocs --strict build, which guards against broken anchors.
Other factors
The bug hunting system found no issues, and there are no prior reviews or outstanding comments on this PR. The main residual risks are factual drift in the newly added behavior descriptions (which I cannot exhaustively verify) and coordination with the two open PRs the author notes will need to slot sections into the new structure. Given the size and the editorial judgment involved, deferring to a human reviewer is the right call rather than shadow-approving.
2 participants
Restructures docs/migration.md so a migrating user (or an agent driving a migration) can find what applies to them at a glance. Documentation only; the diff is one file.
Motivation and Context
The migration guide grew by accretion: one section per breaking PR, in merge order, under four coarse buckets (Breaking Changes / Deprecations / Bug Fixes / New Features). Finding "what hits me" meant reading 1700 lines, several entries described 2026-07-28 features rather than v1-to-v2 breaks, some real breaks were filed under Bug Fixes or New Features, and a number of breaks were missing entirely.
This PR reworks the page along one rule: a section belongs if migrated v1 code, talking to a 2025-11-25 peer, behaves observably differently. Adopting the 2026-07-28 revision is the whats-new page's territory, not this page's.
What changed:
How Has This Been Tested?
Every section's claims were exercised against both runtimes (mcp 1.28.1 and this branch): removed-API claims by importing on both sides, behavior claims with small scripts (including wire captures behind the _meta and mode='legacy' statements), and code examples by running them. mkdocs build --strict passes (the strict build fails on dead anchors, so the eight heading anchors that whats-new.md deep-links are unchanged), and markdownlint passes.
Breaking Changes
None; documentation only.
Types of changes
Checklist
Additional context
AI Disclaimer