From c26d1fde3fa3366fcdd9541396af982d623148a1 Mon Sep 17 00:00:00 2001
From: Aymen Hammouda <hammouda.aymen@gmail.com>
Date: Thu, 14 May 2026 22:33:24 +0200
Subject: [PATCH] docs(release): add mcp-publisher validate pre-tag check +
 backfill phase issue links
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two related housekeeping changes after the v0.1.5 → v0.1.6 release arc:

1. .github/RELEASE.md Pre-Release Verification checklist now includes
   running ./mcp-publisher validate server.json against the live MCP
   Registry endpoint before tagging. The v0.1.5 release was a half-
   publish (PyPI succeeded, MCP Registry rejected the 152-char
   description for exceeding the 100-char schema limit) and would have
   been prevented by this 10-second local check.

2. .planning/ROADMAP.md backlog table now links the three phase rows to
   the live GitHub issues opened after PR #27 (#32, #33, #34).

Both changes are documentation-only; no code or workflow changes.
---
 .github/RELEASE.md   | 6 ++++++
 .planning/ROADMAP.md | 6 +++---
 2 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/.github/RELEASE.md b/.github/RELEASE.md
index ab415e0..62a9102 100644
--- a/.github/RELEASE.md
+++ b/.github/RELEASE.md
@@ -85,6 +85,12 @@ Complete these steps in order. Each step has a checkbox -- do not skip ahead.
   ```bash
   grep '^version' pyproject.toml
   ```
+- [ ] `server.json` validates against the live MCP Registry schema. MCP Registry enforces stricter limits than PyPI (e.g. `description ≤ 100 chars`); validating before the tag prevents a half-published release (PyPI succeeds while MCP Registry rejects, as happened on v0.1.5 → recovered in v0.1.6):
+  ```bash
+  curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+  ./mcp-publisher validate server.json
+  ```
+  Must report `✅ server.json is valid`. If validation fails, shorten the `server.json` `description` on `main` before tagging (the `pyproject.toml` description is unbounded by this constraint and can stay longer).
 - [ ] Integration tests from `.github/INTEGRATION-TEST.md` are complete and signed off
 - [ ] Doctor subcommand passes:
   ```bash
diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md
index ebcb080..ce1f66a 100644
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@@ -9,9 +9,9 @@
 
 | Phase | Title | Tool surface | Issue |
 |-------|-------|--------------|-------|
-| 09 | `compare_versions(symbol, v1, v2)` | New MCP tool | #TBD-link-after-PR-merges |
-| 10 | `whatsnew_for_version(version)` | New MCP tool | #TBD-link-after-PR-merges |
-| 11 | `detect_python_version` v2 (venv-aware) | Existing tool enhancement | #TBD-link-after-PR-merges |
+| 09 | `compare_versions(symbol, v1, v2)` | New MCP tool | [#32](https://github.com/ayhammouda/python-docs-mcp-server/issues/32) |
+| 10 | `whatsnew_for_version(version)` | New MCP tool | [#33](https://github.com/ayhammouda/python-docs-mcp-server/issues/33) |
+| 11 | `detect_python_version` v2 (venv-aware) | Existing tool enhancement | [#34](https://github.com/ayhammouda/python-docs-mcp-server/issues/34) |
 
 These are planned, not committed. Phase CONTEXTs at [`phases/09-compare-versions/`](phases/09-compare-versions/09-CONTEXT.md), [`phases/10-whatsnew/`](phases/10-whatsnew/10-CONTEXT.md), [`phases/11-detect-venv/`](phases/11-detect-venv/11-CONTEXT.md). Implementation kickoff requires `/gsd-plan-phase 0X`.