Prepare release machinery for v2 pre-releases#2831
Merged
Conversation
- Point the package readme at README.v2.md so PyPI renders the v2 docs on pre-release pages; refresh its stale banner, replace GitHub-only alert syntax that PyPI's renderer shows as literal text, and convert relative links to absolute URLs (PyPI has no base URL to resolve them) - Mark the distribution Development Status :: 3 - Alpha - comment-on-release: select the previous release by ancestry on the same major line instead of list order, so a release on one line never compares against a release on another; paginate the commit range instead of truncating at one response; tolerate releases whose tag no longer resolves; label comments on pre-releases as such - Document the v2 pre-release flow in RELEASE.md (pre-release flag, --target, curated notes, yank-don't-delete) - State the pre-release security-fix policy in SECURITY.md
State the alpha status and per-alpha breakage expectation, the beta and stable target dates alongside the 2026-07-28 spec release, the planned backwards-compatibility shims, v1.x's maintenance-mode status, the mcp<2 upper-bound ask for dependents, and the Discord feedback channel.
- comment-on-release: pick the previous release by smallest ahead_by across all same-major releases instead of trusting list order (releases published from drafts keep their draft creation date, so list order can hide the true predecessor); check the major line before comparing so cross-line candidates cost no API calls; skip only candidates whose tag no longer resolves and fail loudly on other compare errors; skip drafts; paginate release and comment listings; cap the commit range at 250 and skip commenting beyond it; derive pre-release wording from the tag as well as the release flag - RELEASE.md: stable releases must target the v1.x branch (the UI defaults to main, which is the v2 rework); the --target commit must contain the release tooling and is ignored if the tag already exists; release notes need absolute links; yanked versions should point at their replacement; bump the Development Status classifier when the line changes stage - README.v2.md: pin install and quickstart commands while v2 is in pre-release; point the docs badge and API reference at the v2 docs site; fix examples against the v2 API (Icon mime_type/sizes, snake_case CallToolResult fields via a re-synced snippet, keyword-only max_tokens, elicitation result shape, request context fields) - snippets: fix the resource-read isinstance in the stdio client example (TextResourceContents, not TextContent) - pyproject: drop the leftover "git" keyword
felixweinberger
approved these changes
Jun 11, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Prepares the repo to publish v2 pre-releases (
2.0.0aN) frommain.Motivation and Context
We want to start publishing v2 alphas to PyPI to get the rework into testers' hands. PEP 440 pre-release semantics keep
2.0.0aNinvisible to anyone onmcp>=1.x(installers only select pre-releases on explicit opt-in), but some repo machinery assumes a single release line, and the published metadata would have been wrong:pyproject.tomlpointed PyPI's long description at the frozen v1README.md, so a pre-release's PyPI page would have shown v1 docs. It now usesREADME.v2.md, with a refreshed banner (alpha status, opt-in install lines, v1.x recommendation, no committed GA date), absolute URLs (PyPI doesn't resolve relative links), and no GitHub-only[!IMPORTANT]alert syntax (PyPI's renderer shows it as literal text).comment-on-release.ymlpicked the "previous release" by list order, which breaks once two release lines publish interleaved:v2.0.0a1's previous release would have beenv1.27.2— a cross-branch compare spanning all ofmainsince the v1.25.0 branch point — and the next v1.x release would then have compared againstv2.0.0a1. It now walks back to the nearest release whose tag is an ancestor of the current tag on the same major line, paginates the commit range instead of truncating at one response, tolerates candidates whose tag no longer resolves, accepts a release re-cut on the same commit, and labels comments on pre-releases as "pre-release". The first release of a new major line has no same-line predecessor, so it intentionally skips commenting rather than commenting on every PR in the new line's history.RELEASE.mddocuments the pre-release flow: verify the matrix on the release commit,gh release create vX --prerelease --target <sha>, curated notes, and yank-don't-delete for broken pre-releases.SECURITY.mdstates the pre-release policy: fixes land only in the newest pre-release; production stays on stable.Development Status :: 3 - Alpha.How Has This Been Tested?
github-scriptbodies from the workflow YAML and executed them under node against the real GitHub API with simulated release lists. 12 scenarios pass, including:v1.27.2→v1.27.1(regression), simulatedv2.0.0a1→ no comments (first of its major line), the next v1.x release skipping the diverged alpha and pickingv1.27.2, incremental alpha-to-alpha selection, a release re-cut on the same commit, a different-major ancestor being skipped rather than aborting the walk, non-version tags, a candidate tag that 404s, and a 230-commit synthetic range collected across 3 pages.text/markdown), the classifier is3 - Alpha, and no relative links remain.Breaking Changes
None for users of the package. The PyPI long description for future uploads from
mainswitches from the v1 README to the v2 README; v1.x releases are unaffected (the v1.x branch has its ownpyproject.toml).Types of changes
Checklist
Additional context
This intentionally does not touch
shared.yml'scontinue-on-error: trueon the test matrix — which currently means failing tests block neitherall-greennor publishing — beyond RELEASE.md telling the release manager to check the individual matrix jobs. Tightening that gate is a candidate follow-up.AI Disclaimer