Repository navigation
go-live 9/9: write the v1 to v2 migration guide #1822
Description
Activity
- changed the title
[-]go-live 8/9: post-swap docs, labels, boards, and integration hygiene[/-][+]go-live 9/9: write the v1 to v2 migration guide[/+]on Jul 27, 2026 Triage: Priority = High
Scored 9/16 with the priority rubric added to
AGENTS.mdin #1891. This card is already approved and sitting in Todo — only Priority was set here, its Status is unchanged.Axis Score Reasoning Severity / impact 3/5 A docs gap rather than a defect, but a consequential one: CLI flags changed substantially and --configsemantics genuinely differ in v2, so the deprecation notice currently sends people somewhere confusing with no map.Urgency / staleness 4/5 The trigger already fired — v2 is published and v1 is deprecated — so the guide is late relative to the event it was meant to accompany, and the #1872 sweep has just pointed 135 reporters at v2. Signal bonuses +2 milestone (v2.2.0) (+1), assigned (+1) Total 9 Lands in the High band (9-11). Related issues. These look connected and may be worth reading together:
- Execute the first v2/main → main milestone merge and cut the release #1876 — the release this guide was scoped to ship alongside
- docs: new modelcontextprotocol.io Inspector documentation for v2 (legacy vs. modern era, more screenshots) #1803 — the paired documentation work for modelcontextprotocol.io
- Triage the open issue backlog: backfill v1/v2 labels, close legacy, board the rest #1872 — the deprecation sweep that just directed a large group of v1 users toward v2
Scores are a starting point, not a verdict — the rubric is meant to be overruled when it's plainly wrong, provided the reason is written down.
- linked a pull request that will close this issuedocs: add the v1 → v2 migration guide #1960
on Aug 11, 2026 - added a commit that references this issue
on Aug 11, 2026
Phase 9 of 9 in the v2 go-live runbook — see #1804 (§10). Pairs with #1803.
Write the v1 → v2 migration guide.
This is the highest-value doc shipped alongside the swap. CLI flags changed substantially, and
--configsemantics are genuinely different in v2 (read-only session file, with--catalogas the writable one). Without this, the deprecation notice sends people somewhere confusing.Tasks
--configvs--catalogsemantics, with before/after examples.inspector-client/inspector-server/inspector-clisub-packages (v2 is a single tarball).