[v1.x] Move the v1.x docs to /v1/ and mark v1.x as the maintenance line - #3177
[v1.x] Move the v1.x docs to /v1/ and mark v1.x as the maintenance line#3177maxisbey merged 1 commit into
Conversation
Sorry, something went wrong.
With v2 becoming the stable release, v1.x moves from the site root to /v1/ and stops deploying the site itself: the combined site is built and deployed from main, which builds this branch's docs into /v1/ via the new scripts/docs/build.sh. A `docs` CI job runs that same script, so a change that breaks the v1 docs fails on this branch rather than at main's next deploy. site_url and the package's Documentation URL move to /v1/ so canonical links, the sitemap, and llms.txt point at where these pages are actually served. The README and landing page now describe v1.x as the maintenance line and send new users to the v2 docs, and every install line pins `mcp<2` so a reader following these docs stays on the 1.x line now that an unpinned install selects 2.x.
📚 Documentation preview
|
Sorry, something went wrong.
There was a problem hiding this comment.
LGTM — docs-only change: URL/banner updates, install-pin edits, and a deploy-workflow → CI-build-check swap, with no SDK code touched.
What was reviewed:
- Checked for stale references to the deleted scripts/build-docs.sh and old modelcontextprotocol.github.io URLs — none remain (the one mention of the old script is a comment pointing at main's copy, which is intentional).
- Verified scripts/docs/build.sh resolves the repo root correctly and that the docs dependency group it syncs exists in pyproject.toml.
- Checked the new docs CI job: it inherits shared.yml's contents: read permission and matches the sibling jobs' action versions; removing deploy-docs.yml also removes this branch's pages: write/id-token: write grants.
- Confirmed the mcp<2 pins and /v1/ links in README/docs are consistent with the new site_url.
Overview
This PR is part of the v2-stable docs re-layout on the v1.x branch. It (1) removes this branch's docs deploy workflow (deploy-docs.yml) so the combined site is built and deployed only from main, (2) moves the branch's build recipe into scripts/docs/build.sh (which main's combined build invokes for the /v1/ tree) and adds a docs CI job to shared.yml that runs the same script, (3) updates site_url and the package Documentation URL to /v1/, and (4) rewrites the README/landing-page banners to describe v1.x as the maintenance line, pinning every install example to mcp<2. No SDK source code, tests, or runtime behavior is touched.
Security risks
None identified. The only workflow change is additive in a low-privilege direction: the deleted deploy workflow carried pages: write and id-token: write, while the new docs job runs under shared.yml's top-level contents: read and uses the same tag-pinned actions (actions/checkout@v5, astral-sh/setup-uv@v7) as the existing jobs in that file. The build script is a straightforward uv sync --frozen + mkdocs build with no untrusted inputs.
Level of scrutiny
Low-to-moderate. This is documentation and docs-CI plumbing, not production code paths. The main things worth checking were mechanical consistency issues, which I verified directly: no dangling references to the removed scripts/build-docs.sh, no leftover modelcontextprotocol.github.io URLs, the docs dependency group referenced by the build script exists in pyproject.toml, and the script's cd correctly lands at the repo root. The bug hunting system also found no issues.
Other factors
The one non-mechanical aspect is the cross-branch deploy dependency: after this merges, v1 docs publish only via main's deploy (companion PR) or a manual dispatch. That coordination and its merge ordering are explicitly documented in the PR description, so it is a known, intentional trade-off rather than something a reviewer needs to catch. The new docs CI job on this PR itself exercises the build script, so the PR's own CI validates the recipe. Broken external deep links to old root paths are acknowledged in the description as accepted.
Sorry, something went wrong.
With v2 becoming the stable release, the v1.x docs move from the site root to /v1/, and this branch stops deploying the docs site itself: the combined site is built and deployed from main (companion PR #3176), which builds this branch's docs into /v1/.
Motivation and Context
After the v2 stable release, the site root serves the current major and each major keeps a permanent path (/v1/, /v2/, ...). Two things follow for this branch: its docs need to describe themselves as living under /v1/, and it must not keep deploying the old layout over the top of main's.
Changes:
Merge order for release day: after #3176 merges, then a manual Deploy Docs dispatch on main so /v1/ rebuilds with this branch's new site_url and banners.
How Has This Been Tested?
The build recipe was exercised locally through its dependency sync; the new docs CI job on this PR runs the same script, so this PR's own CI is the validation of the build.
Breaking Changes
None for SDK users. v1 doc URLs move from the root to /v1/...; existing external deep links to the old root paths will 404 (accepted as part of the layout change). Note that once merged, a docs edit on this branch is published by main's next deploy or a manual dispatch rather than by its own workflow.
Types of changes
Checklist
AI disclosure
AI assistance was used to implement and validate this change; I reviewed the result and take responsibility for it.
AI Disclaimer