π The fast, Pythonic way to build MCP servers and clients.
skills: add release skill with changelog entry helper (#4982)
nate nowack07659a00ded6
diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.mdnew file mode 100644index 000000000..4571814b5--- /dev/null+++ b/.claude/skills/release/SKILL.md@@ -0,0 +1,161 @@+---+name: release+description: Cut a FastMCP release end to end. Use when the maintainer says "cut a release", "prep a patch", "ship 4.x.y", or asks what a release would contain. Covers the notes preview, the title pun, the docs changelog PR that must land before the tag, the tag itself, the publish fan-out, and verifying gofastmcp.com actually deployed.+---++# Cutting a release++A release is a tag on the branch that owns the line: `<branch>` below is `main` for+the current major and `release/3.x` for 3.x maintenance. Every step runs against that+branch, including the docs PR, so a maintenance entry lands in the maintenance+branch'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+tagged commit, so the docs PR always lands first. PyPI releases are immutable; a bad+one gets a follow-up patch, never a re-tag.++## Procedure++1. **Preview what's in it.**++ ```bash+ git fetch origin && git log v<prev>..origin/<branch> --format='%h %s'+ gh api -X POST repos/PrefectHQ/fastmcp/releases/generate-notes \+ -f tag_name=v<new> -f target_commitish=<branch> -f previous_tag_name=v<prev> --jq .body+ ```++ Read the two most recent releases for voice: `gh release list -L 5`, then+ `gh release view <tag>` on each.++2. **Propose titles.** Titles are `v<version>: <pun>`, pun on the release's main+ theme. Read the whole title history first, `gh release list -L 60`, so the+ options stay on brand: two to four words, a familiar phrase bent toward the+ theme ("Cache Me If You Can", "Trust, but Proxy", "Come Back Any Time"),+ and a running family for a major's prereleases ("Fourst Contact", "Group+ Effourt"). Offer several; the maintainer picks. Draft the handwritten notes at the+ same time: one or two sentences for a patch, narrative prose for a point release.+ Get sign-off on both before anything is pushed.++3. **Write the notes file** outside the repository (a temp directory), intro only.+ The release title is the heading, so the file has none.++4. **Docs entries.** Branch `docs/changelog-<new>` from `origin/<branch>` and insert+ both blocks (the last argument is the branch the notes are generated against):++ ```bash+ uv run .claude/skills/release/scripts/changelog_entry.py v<new> v<prev> "<pun>" /tmp/notes.md <branch>+ ```++ Validate, and repeat until it reports no errors; a parse error names the file+ and line:col:++ ```bash+ cd docs && npx --yes mint@latest broken-links+ ```++ (`@latest` on purpose: the hosted Mintlify build is always current.) Commit,+ push, open the PR titled `docs: add v<new> changelog entries` with base+ `<branch>` and a one-line body, and merge it. Branch policy needs `--admin` on a maintainer-driven release.+ The docs PR itself appears in the GitHub notes but not in the mirror; that is+ expected.++5. **Tag**, immediately after the docs PR merges. Re-run the step 1 preview first;+ if `<branch>` moved, delete the entry blocks from both docs files, re-run the+ helper (it refuses to insert a label that already exists), and land that as a+ follow-up docs PR before tagging.++ ```bash+ gh release create v<new> --target <branch> --title "v<new>: <pun>" \+ --generate-notes --notes-start-tag v<prev> --notes-file /tmp/notes.md+ ```++ `v<prev>` is the last stable tag on that branch. The compare link at the bottom of the created release must read `v<prev>...v<new>`.++6. **Watch the fan-out.** The slim run is keyed to the tag; the others are+ `workflow_run` events on the default branch, so select them by workflow name.+ The slim run appears within a minute of the tag; the `fastmcp` run is queued the+ moment slim succeeds, so watch slim to completion first and the newest `fastmcp`+ run is the right one.++ ```bash+ gh run watch $(gh run list --event release --branch v<new> --limit 1 --json databaseId --jq '.[0].databaseId') --exit-status+ gh run watch $(gh run list --workflow "Publish fastmcp to PyPI" --limit 1 --json databaseId --jq '.[0].databaseId') --exit-status+ ```++ 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+ `Publish FastMCP v<new> docs` against `published-docs`:++ ```bash+ gh pr list --base published-docs --state open --json number,title+ gh pr merge <n> --merge --admin+ ```++ Then read Mintlify's verdict on the new tip. The check-run is the only signal+ that a deploy happened; the merge alone proves nothing. It starts within a+ minute of the merge and `conclusion` is `null` until it finishes:++ ```bash+ git fetch origin published-docs+ sha=$(git rev-parse origin/published-docs)+ gh api repos/PrefectHQ/fastmcp/commits/$sha/check-runs \+ --jq '.check_runs[] | select(.name=="Mintlify Deployment") | .conclusion, .output.text'+ ```++ Verify through the markdown endpoints, which bypass the HTML edge cache:+ `curl -fsS https://gofastmcp.com/changelog.md | grep -c "<pun>"`, and the same+ for `updates.md` and any page the release touched.++## Publishing docs by hand++Used when a deploy failed and was fixed on `main`, or for a docs change outside a+release. The publication commit must match `main`'s tree exactly.++```bash+git fetch origin main published-docs+git checkout -b publish-docs-<topic> origin/published-docs+git read-tree -m -u origin/main && git commit -m "docs: publish main @ $(git rev-parse --short origin/main)"+git diff --quiet HEAD origin/main && echo "tree matches main"+git push -u origin publish-docs-<topic>+gh pr create --base published-docs --title "docs: publish main to published-docs (<what>)" --body "<one line>"+gh pr merge <n> --merge --admin+```++Then repeat the check-run and endpoint verification from step 7.++## Template: notes file for a patch++```+`ClientGroup` now reference-counts its context the way `Client` does, so entering a+connected group from a nested block or a concurrent task reuses the existing+connections instead of raising.+```++## Gotchas++- Mintlify keeps its per-file hashes even when a deploy fails on a parse error, so+ the next successful deploy only rebuilds files changed since the failure. After+ fixing a parse error, make a small wording edit to every path the failed run+ listed under "Updating targeted paths", merge that to `main`, and publish by hand.+- `--generate-notes` copies PR titles verbatim; a title containing `<1`, `{`, or `}`+ breaks MDX. `scripts/changelog_entry.py` wraps those in backticks; the validator+ in step 4 catches anything it misses.+- No Mintlify check-run on the new `published-docs` tip within a few minutes means+ Mintlify never picked the merge up, and there is no CLI trigger. Read+ https://status.mintlify.com first; their deploy queue backs up during incidents+ and the merge deploys on its own once it drains.+- Without `--notes-start-tag`, a prerelease tag becomes the changelog start and the+ PR list is silently truncated.+- Maintenance releases publish packages and notes but never repoint `published-docs`;+ their changelog entries go on the maintenance branch under the matching major section.++## Check before finishing++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>"`.diff --git a/.claude/skills/release/scripts/changelog_entry.py b/.claude/skills/release/scripts/changelog_entry.pynew file mode 100644index 000000000..efa9d7d1d--- /dev/null+++ b/.claude/skills/release/scripts/changelog_entry.py@@ -0,0 +1,144 @@+"""Insert the release entry into docs/changelog.mdx and docs/updates.mdx.++Usage:+ uv run .claude/skills/release/scripts/changelog_entry.py v4.0.1 v4.0.0 "Come Back Any Time" notes.md+ uv run .claude/skills/release/scripts/changelog_entry.py ... --print # render only++Reads the maintainer-approved notes file for the intro paragraph and pulls the+PR list from GitHub's generate-notes API, so the docs entry matches what+`gh release create --generate-notes` will append. Each block is inserted above+the newest existing `<Update` in its file. Run from the repository root.+"""++from __future__ import annotations++import datetime as dt+import re+import subprocess+import sys+from pathlib import Path++REPO = "PrefectHQ/fastmcp"+++def generate_notes(tag: str, previous: str, target: str) -> str:+ out = subprocess.check_output(+ [+ "gh",+ "api",+ "-X",+ "POST",+ f"repos/{REPO}/releases/generate-notes",+ "-f",+ f"tag_name={tag}",+ "-f",+ f"target_commitish={target}",+ "-f",+ f"previous_tag_name={previous}",+ "--jq",+ ".body",+ ],+ text=True,+ )+ return out+++def linkify(body: str) -> str:+ body = re.sub(r"<!--.*?-->\n?", "", body, flags=re.S)+ body = body.replace("## What's Changed\n", "")+ body = re.sub(+ r"by @([\w-]+) in https://github\.com/" + re.escape(REPO) + r"/pull/(\d+)",+ r"by [@\1](https://github.com/\1) in [#\2](https://github.com/"+ + REPO+ + r"/pull/\2)",+ body,+ )+ body = re.sub(+ r"\* @([\w-]+) made their first contribution in https://github\.com/"+ + re.escape(REPO)+ + r"/pull/(\d+)",+ r"* @\1 made their first contribution in [#\2](https://github.com/"+ + REPO+ + r"/pull/\2)",+ body,+ )+ body = re.sub(+ r"\*\*Full Changelog\*\*: https://github\.com/"+ + re.escape(REPO)+ + r"/compare/(\S+)",+ r"**Full Changelog**: [\1](https://github.com/" + REPO + r"/compare/\1)",+ body,+ )+ return body.strip()+++def escape_mdx(text: str) -> str:+ """Backtick-wrap bare `<digit`, `{`, `}` outside code spans; MDX reads them as JSX."""++ def fix(line: str) -> str:+ parts = line.split("`")+ for i in range(0, len(parts), 2):+ parts[i] = re.sub(r"(<\d[^\s`]*)", r"`\1`", parts[i])+ parts[i] = re.sub(r"(\{[^{}]*\})", r"`\1`", parts[i])+ parts[i] = re.sub(r"(?<!`)([{}])(?!`)", r"`\1`", parts[i])+ return "`".join(parts)++ return "\n".join(fix(line) for line in text.splitlines())+++def insert_above_newest(path: Path, block: str) -> None:+ text = path.read_text()+ idx = text.find("<Update ")+ if idx < 0:+ raise SystemExit(f"{path}: no <Update block found to insert above")+ if block.splitlines()[0] in text:+ raise SystemExit(f"{path}: an entry with this label already exists")+ path.write_text(text[:idx] + block + "\n" + text[idx:])+++def main() -> None:+ args = [a for a in sys.argv[1:] if not a.startswith("--")]+ render_only = "--print" in sys.argv+ if len(args) < 4:+ raise SystemExit(__doc__)+ tag, previous, pun, notes_path = args[:4]+ target = args[4] if len(args) > 4 else "main"+ version = tag.lstrip("v")+ today = dt.date.today()+ intro = " ".join(+ line.strip() for line in open(notes_path).read().split("\n") if line.strip()+ )+ body = escape_mdx(linkify(generate_notes(tag, previous, target)))+ url = f"https://github.com/{REPO}/releases/tag/{tag}"++ changelog = f'''<Update label="{tag}" description="{today.isoformat()}">++**[{tag}: {pun}]({url})**++{intro}++{body}++</Update>+'''+ updates = f'''<Update label="FastMCP {version}" description="{today.strftime("%B %-d, %Y")}" tags={{["Releases"]}}>+<Card+title="FastMCP {tag}: {pun}"+href="{url}"+cta="Read the release notes"+>+{intro}+</Card>+</Update>+'''+ if render_only:+ print(changelog)+ print(updates)+ return+ insert_above_newest(Path("docs/changelog.mdx"), changelog)+ insert_above_newest(Path("docs/updates.mdx"), updates)+ print("inserted entries into docs/changelog.mdx and docs/updates.mdx")+++if __name__ == "__main__":+ main()diff --git a/CLAUDE.md b/CLAUDE.mdindex 1031b8b68..a1b9f9f4e 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -85,6 +85,8 @@ When modifying MCP functionality, changes typically need to be applied across al### Releases+The executable procedure lives in `.claude/skills/release/SKILL.md`; load that skill to cut one. The policy below is the contract it implements.+Only cut releases when the maintainer explicitly asks. Tags follow `v<version>` (e.g., `v3.2.0`). Always pass `--generate-notes` so the auto-generated changelog appears at the bottom.**The title pun is critical.** Titles follow `v<version>: <pun>` where the pun relates to the most important theme of the release. Propose multiple options and let the maintainer choose β never pick one yourself. Look at recent releases for tone (e.g., "Code to Joy" for the code mode release, "Three at Last" for 3.0).