π The fast, Pythonic way to build MCP servers and clients.
docs: preserve docs routing metadata and release guidance (#6320)
nate nowack6884153bfe5b
diff --git a/.agents/skills/docs/SKILL.md b/.agents/skills/docs/SKILL.mdindex d6cfa15b8..ac7a226e1 100644--- a/.agents/skills/docs/SKILL.md+++ b/.agents/skills/docs/SKILL.md@@ -5,7 +5,7 @@ description: Write or revise a page under docs/ for gofastmcp.com. Use when addi# FastMCP docs-The docs are a Mintlify site built from `docs/`. A page exists only when `docs/docs.json` lists it, and a feature exists only when a page documents it. `docs/python-sdk/**` is generated from docstrings by a bot; edit the docstring, not the page.+The docs are a Mintlify site built from `docs/` on `published-docs`, served at `https://gofastmcp.com/docs`. The separate `PrefectHQ/gofastmcp-website` repository deploys its `main` branch to Vercel, serves the root landing page, and proxies these docs under `/docs`. Author docs here on `main`; website changes belong in that repository. A page exists only when `docs/docs.json` lists it, and a feature exists only when a page documents it. `docs/python-sdk/**` is generated from docstrings by a bot; edit the docstring, not the page.## Procedurediff --git a/.agents/skills/release/SKILL.md b/.agents/skills/release/SKILL.mdindex 562a4456d..64d9b45d7 100644--- a/.agents/skills/release/SKILL.md+++ b/.agents/skills/release/SKILL.md@@ -10,8 +10,12 @@ the current major and `release/3.x` for 3.x maintenance. Every step runs againstbranch, including the docs PR, so a maintenance entry lands in the maintenancebranch's own changelog above its newest 3.x entry. The tag triggers `Publish fastmcp-slim to PyPI`;its success fans out to `fastmcp-tasks`, `fastmcp-remote`, and `fastmcp`, and the-`fastmcp` publish job opens the `published-docs` PR that makes gofastmcp.com reflect-the release. Two hand-maintained docs files mirror every release and must be on the+`fastmcp` publish job opens the `published-docs` PR for stable release-triggered+publication when the release SHA is an ancestor of the default branch. Prereleases+and manual package-workflow dispatch do not open that PR. Mintlify builds `docs/`+from `published-docs` at `https://gofastmcp.com/docs`; the separate+`PrefectHQ/gofastmcp-website` repository deploys its `main` to Vercel for the landing+page and `/docs` proxy. Two hand-maintained docs files mirror every release and must be on thetagged commit, so the docs PR always lands first. PyPI releases are immutable; a badone gets a follow-up patch, never a re-tag.@@ -142,8 +146,9 @@ one gets a follow-up patch, never a re-tag.Confirm each package with `curl -fsS https://pypi.org/pypi/<pkg>/<new>/json | jq .info.version`;the unversioned endpoint lags a few minutes.-7. **Publish docs** (`main` releases only; maintenance releases skip this step and- leave gofastmcp.com on the current major). When the `fastmcp` run finishes, its last job has opened+7. **Publish docs** (eligible stable releases from the default-branch lineage only;+ maintenance releases leave gofastmcp.com/docs on the current major). After a+ successful eligible `fastmcp` run, its last job has opened`Publish FastMCP v<new> docs` against `published-docs`:```bash@@ -151,6 +156,8 @@ one gets a follow-up patch, never a re-tag.gh pr merge <n> --merge --admin```+ Before merging, apply the publication checks below to the PR's exact release+ tree; a later fix on `main` does not change an existing release candidate.Merging pushes `published-docs`, which runs the `Deploy docs` workflow: it asksMintlify's admin API for a deployment of the tip and waits for the verdict.That run is the signal that the site changed; the merge alone proves nothing.@@ -165,7 +172,7 @@ one gets a follow-up patch, never a re-tag.`gh workflow run deploy-docs.yml --ref published-docs` once their incident clears.Verify through the markdown endpoints, which bypass the HTML edge cache:- `curl -fsS https://gofastmcp.com/changelog.md | grep -c "<pun>"`, and the same+ `curl -fsS https://gofastmcp.com/docs/changelog.md | grep -c "<pun>"`, and the samefor `updates.md` and any page the release touched.## Publishing docs by hand@@ -173,6 +180,9 @@ one gets a follow-up patch, never a re-tag.Used when a deploy failed and was fixed on `main`, or for a docs change outside arelease. The publication commit must match `main`'s tree exactly.+Before preparing the PR, apply the publication checks below to the selected main+tree. This publishes the entire tree, not just the changed page.+```bashgit fetch origin main published-docsgit checkout -b publish-docs-<topic> origin/published-docs@@ -185,6 +195,30 @@ gh pr merge <n> --merge --adminThen watch the `Deploy docs` run and verify the endpoints as in step 7.+## Publication checks++Invoking this skill or requesting documentation alone does not authorize a merge,+package release, docs publication, or infrastructure change. Use the maintainer's+explicit scope. Follow repository review policy unless the maintainer explicitly+authorizes an available admin merge; example flags alone do not grant permission.+An agent review is not an independent human GitHub approval.++Compare `docs/docs.json` in the actual publication candidate (the release SHA for+an automatic PR, selected main SHA for a manual PR) with `published-docs`. Preserve+`logo.href = https://gofastmcp.com`,+`seo.metatags.canonical = https://gofastmcp.com/docs`, and+`seo.organization.logo = https://gofastmcp.com/docs/assets/brand/wordmark.png`.+If missing, hold publication and reconcile the source and candidate through review.+A main-only fix does not repair an already generated release tree.++After Deploy docs succeeds, verify changed pages and their `.md` forms under+`/docs`, search, assets, and version switching. For routing changes also verify+old links redirect to one `/docs` prefix with queries and browser anchors intact,+production canonicals, and root `/mcp` initialization, tools/list, and read-only+search. Ordinary publication leaves domains and Mintlify's `/docs` base path alone.+Manual dispatch or rerunning an old Deploy docs run deploys the configured tip;+it does not restore that run's historical tree.+## Template: notes file for a patch```@@ -212,5 +246,5 @@ connections instead of raising.Each of these prints a count above zero:`curl -fsS https://pypi.org/pypi/fastmcp/<new>/json | grep -c '"version"'`,-`curl -fsS https://gofastmcp.com/changelog.md | grep -c "<pun>"`,-`curl -fsS https://gofastmcp.com/updates.md | grep -c "<pun>"`.+`curl -fsS https://gofastmcp.com/docs/changelog.md | grep -c "<pun>"`,+`curl -fsS https://gofastmcp.com/docs/updates.md | grep -c "<pun>"`.diff --git a/AGENTS.md b/AGENTS.mdindex ddf9d8033..846abf50f 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -129,7 +129,7 @@ Load the `release` skill to cut one; it holds the procedure. The policy it imple- The handwritten notes need the maintainer's sign-off: one or two sentences for a patch, narrative prose for a point release.- Generate the changelog from the last stable tag (`previous_tag_name` in the notes API, or `--notes-start-tag` when using CLI generation) so a prerelease tag never truncates it. Complete contributor attribution before publication and publish those completed notes with `--notes-file`.- Merge the docs changelog PR on the release branch immediately *before* tagging, so the entry is in the tagged commit.-- gofastmcp.com serves the `published-docs` branch, which accepts changes only through PRs.+- gofastmcp.com/docs serves Mintlify docs from `published-docs`, which accepts changes only through PRs. `main` is the docs authoring source. The root website is maintained separately in `PrefectHQ/gofastmcp-website` and deployed by Vercel from its `main` branch.### Commit Messages and Agent Attributiondiff --git a/docs/development/releases.mdx b/docs/development/releases.mdxindex 541b256be..11b4dca70 100644--- a/docs/development/releases.mdx+++ b/docs/development/releases.mdx@@ -45,8 +45,8 @@ Publishing a release triggers the package workflows. On the current line, `fastm## Publishing documentation-The live site serves the `published-docs` branch, not `main`. A stable release from `main` opens a PR that copies the release tree to `published-docs` after package publishing succeeds. A maintainer merges that PR, then verifies the `Deploy docs` workflow completed successfully.+The documentation at `https://gofastmcp.com/docs` is built by Mintlify from `docs/` on `published-docs`; `main` is the authoring source. The separate `PrefectHQ/gofastmcp-website` repository deploys its `main` branch to Vercel for the root landing page and `/docs` proxy. A stable release from the default-branch lineage opens a PR that copies the exact release tree to `published-docs` after package publishing succeeds. A maintainer merges that PR, then verifies the `Deploy docs` workflow completed successfully and checks the changed public docs.-Prereleases do not open that publication PR automatically. Docs-only changes between releases can be published through a PR that synchronizes `main` to `published-docs`; follow the release skill's manual publication procedure. Do not push directly to the publication branch.+Prereleases and manual package-workflow dispatch do not open that publication PR automatically. Docs-only changes between releases can be published through a PR that synchronizes `main` to `published-docs`; follow the release skill's manual publication procedure and publication checks, including preservation of `/docs` metadata in the candidate tree. Do not push directly to the publication branch. Ordinary publication does not change domains or Mintlify's `/docs` base path.Maintenance releases update their own changelog and packages without repointing the current documentation site. The `docs/v2/` and `docs/v3/` trees preserve historical documentation; outside their release changelogs, they are frozen snapshots.diff --git a/docs/docs.json b/docs/docs.jsonindex 97fc92616..cdd120904 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -59,6 +59,7 @@"drilldown": false},"logo": {+ "href": "https://gofastmcp.com","dark": "/assets/brand/wordmark-white.png","light": "/assets/brand/wordmark.png"},@@ -564,11 +565,14 @@"prompt": "Search the docs..."},"seo": {+ "metatags": {+ "canonical": "https://gofastmcp.com/docs"+ },"organization": {"name": "FastMCP","legalName": "Prefect Technologies, Inc.","url": "https://gofastmcp.com",- "logo": "https://gofastmcp.com/assets/brand/wordmark.png",+ "logo": "https://gofastmcp.com/docs/assets/brand/wordmark.png","sameAs": ["https://github.com/PrefectHQ/fastmcp","https://x.com/fastmcp",