Link the released 2026-07-28 spec and point migrators at /v1/ - #3214
Conversation
The README banner still linked the spec's release-candidate blog post; the specification is now published, so link it directly. Also give the migration guide's help section the same pointer to the v1.x maintenance-line docs that index.md and whats-new.md already carry. No-Verification-Needed: doc-only change
📚 Documentation preview
|
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
LGTM — two straightforward documentation link updates.
What was reviewed
- README banner spec link: the new URL matches the canonical 2026-07-28 spec URL already used in the codebase (
SPEC_2026_BASE_URLintests/interaction/_requirements.py). - New migration-guide
/v1/pointer: consistent with the same link indocs/index.mdanddocs/whats-new.md, and its wording matches the maintenance-line policy in AGENTS.md.
Extended reasoning...
Overview
This PR changes two documentation files: README.md swaps the spec link in the v2 banner from the release-candidate blog post to the published 2026-07-28 specification page, and docs/migration.md appends a two-line pointer to the v1.x maintenance-line docs at /v1/ in the "Need Help?" section. No code, config, or build files are touched.
Security risks
None. The changes are Markdown-only link edits pointing at first-party domains (modelcontextprotocol.io and py.sdk.modelcontextprotocol.io) already referenced throughout the repository.
Level of scrutiny
Minimal scrutiny is appropriate: this is a docs-only PR with no behavioral impact. The main things worth verifying were link correctness and consistency, both of which check out — the new spec URL exactly matches SPEC_2026_BASE_URL (https://modelcontextprotocol.io/specification/2026-07-28) asserted in tests/interaction/test_coverage.py, and the /v1/ URL matches the identical links in docs/index.md and docs/whats-new.md.
Other factors
The bug hunting system found no issues, and the PR timeline has no outstanding reviewer comments. The added migration-guide text accurately reflects the repository's stated v1.x maintenance policy (critical bug fixes and security patches only). The change fits squarely in the "simple, mechanical, obvious" approval category.
Put it right under the intro as an admonition, matching the "Coming from v1?" note elsewhere, instead of at the end of the Need Help section where nobody scrolls to. No-Verification-Needed: doc-only change
There was a problem hiding this comment.
LGTM — two small docs-only link fixes, no code changes.
What was reviewed
- README banner: spec link swapped from the release-candidate blog post to the published spec URL (
modelcontextprotocol.io/specification/2026-07-28), matching the format of the existingspec-urlbadge; rest of the line is unchanged. docs/migration.md: new "Not ready to migrate yet?" admonition points at/v1/— same URL and wording pattern already used indocs/index.mdanddocs/whats-new.md.- Checked no other references to the old release-candidate blog link remain in the repo.
Extended reasoning...
Overview
This PR touches only README.md and docs/migration.md. It replaces the README banner's link to the 2026-07-28 release-candidate blog post with the now-published specification URL, and adds a "Not ready to migrate yet?" MkDocs admonition to the top of the migration guide pointing at the v1.x maintenance-line docs at /v1/.
Security risks
None. The change is purely documentation — no code, config, dependency, or CI changes. The new link targets are on the official modelcontextprotocol.io and py.sdk.modelcontextprotocol.io domains already used throughout the repo.
Level of scrutiny
Low. This is exactly the kind of simple, mechanical documentation change suitable for shadow approval: two hyperlink edits following patterns already established elsewhere in the docs. I verified the new spec URL format matches the repo's existing spec-url badge (/specification/latest), that the /v1/ pointer matches the identical references in docs/index.md and docs/whats-new.md, and that no stale references to the release-candidate blog post remain anywhere in the repo.
Other factors
The bug hunting system found no issues. The only timeline activity is the automated docs-preview bot comment, and the docs preview built successfully against the PR commit. The change is consistent with the repo's branching-model guidance (README documents v2, v1 docs live at /v1/), and no migration-guide or test updates are required for a docs-only link fix.
1 participant
Two small link fixes in the v2-facing docs.
Motivation and Context
The README banner linked the spec's release-candidate blog post; the 2026-07-28 specification is published now, so link it directly. The migration guide's "Need Help?" section also gets the same pointer to the v1.x maintenance-line docs (
/v1/) thatindex.mdandwhats-new.mdalready carry.How Has This Been Tested?
Link targets checked (spec URL returns 200).
Breaking Changes
None.
Types of changes
Checklist
AI Disclaimer