Skip to content

Document the two-line release process for stable v2 #3179

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
maxisbey merged 2 commits into from
Jul 28, 2026
+114 −52
Merged

Document the two-line release process for stable v2 #3179

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8ba2305
Document the two-line release process for stable v2
maxisbey Jul 25, 2026
76075f2
Address review nits in the release process doc
maxisbey Jul 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
166 changes: 114 additions & 52 deletions RELEASE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,63 +7,125 @@
`[tool.hatch.metadata.hooks.uv-dynamic-versioning].dependencies`.
2. Upgrade lock with `uv lock --resolution lowest-direct`
Comment on lines 7 to 8

@claude claude Bot Jul 28, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟣 Pre-existing issue (this line is unchanged by the PR): step 2 of "Bumping Dependencies" says "Upgrade lock with uv lock --resolution lowest-direct", but that command doesn't upgrade anything — it re-resolves every direct dependency down to its declared floor, mass-downgrading the committed uv.lock (pydantic 2.12.5 → 2.12.0, typer 0.17.4 → 0.16.0, …) and persisting resolution-mode = "lowest-direct" so later plain uv lock runs silently stay in that mode. Since this PR's purpose is making RELEASE.md the accurate operative runbook, consider fixing the one carried-over stale line too: uv lock or uv lock --upgrade-package <package> (the procedure AGENTS.md already documents).

Extended reasoning...

The bug. The "Bumping Dependencies" section (RELEASE.md lines 7-8) survives this rewrite unchanged, and its step 2 — "Upgrade lock with uv lock --resolution lowest-direct" — is wrong in a way that would actively damage the repo if followed. --resolution lowest-direct tells uv to resolve every direct dependency in the workspace to the lowest version satisfying its specifier, i.e. its declared floor. Running it doesn't upgrade the lock after a floor bump; it rewrites uv.lock as a mass downgrade of everything else.

Evidence the committed lock was never produced this way. The current uv.lock is a standard highest-resolution lock: (1) it contains no [options] section / resolution-mode entry, which uv writes whenever a non-default --resolution is used; (2) locked versions sit above their floors — pydantic 2.12.5 vs >=2.12.0 (pyproject.toml:129), typer 0.17.4 vs >=0.16.0 (pyproject.toml:29), anyio 4.10.0. A lowest-direct resolution would pin all of these at their floors. So the documented command has never actually been used to produce the committed lock, and running it would produce a huge unintended diff.

Step-by-step proof of the failure. (1) A maintainer bumps one dependency floor per step 1, e.g. raises httpx to >=0.28. (2) Following step 2 verbatim, they run uv lock --resolution lowest-direct. (3) uv re-resolves the whole workspace in lowest-direct mode: typer drops 0.17.4 → 0.16.0, pydantic 2.12.5 → 2.12.0, and every other direct dependency falls to its floor. (4) uv also records resolution-mode = "lowest-direct" in the lockfile's [options], so every subsequent plain uv lock silently stays in lowest-direct mode. (5) Once committed, CI's "locked" matrix leg (which installs --frozen from uv.lock) and every developer environment run against floor versions — while the dedicated lowest-direct leg (.github/workflows/shared.yml:64-68, which applies --upgrade --resolution lowest-direct at install time precisely so the committed lock stays highest-resolution) becomes redundant. The repo loses its highest-resolution test coverage entirely.

Why nothing else prevents it. RELEASE.md is the operative runbook a maintainer follows verbatim, and the instruction is internally self-contradictory only on close reading (a command labeled "Upgrade lock" performs a downgrade). It also directly contradicts the repo's own AGENTS.md, which documents the correct procedure: "Upgrading: uv lock --upgrade-package <package>" and "Always pass --frozen so uv doesn't rewrite uv.lock as a side effect."

Why flag it on this PR despite being untouched. All four verifiers confirmed the line predates this PR (it dates to when RELEASE.md was created) and sits as unchanged context above the rewrite — hence pre-existing, not blocking. But the PR's stated purpose is making RELEASE.md accurate for the person actually cutting releases, and this is the one remaining section carried over unreviewed. Fixing it is a one-line change.

Fix. Change step 2 to "Upgrade lock with uv lock --upgrade-package <package>" (matching AGENTS.md), or simply uv lock if the intent is a plain re-lock after editing the floor.


## Major or Minor Release

Stable releases are cut from the `v1.x` branch. Create a GitHub release via UI
with the tag being `vX.Y.Z` where `X.Y.Z` is the version and the release title
being the same, and **set the tag's target to the `v1.x` branch** — the UI
defaults to `main`, which is the v2 rework, and a v1 tag created there would
publish the v2 codebase as a stable release. Then ask someone to review the
release.

The package version will be set automatically from the tag.

## v2 Pre-releases

v2 pre-releases are cut from `main` with a PEP 440 pre-release tag: `v2.0.0aN`
for alphas, later `bN`/`rcN` for betas and release candidates.

A release publishes two distributions, `mcp` and `mcp-types`, at the same
version, and the `mcp` wheel exact-pins `mcp-types`. Before the first release
that includes both, the `mcp-types` PyPI project must be given the same
trusted publisher as `mcp` (this repository, workflow `publish-pypi.yml`,
environment `release`) and the same owners — without it the `mcp-types`
upload is rejected. If only some of the files upload, fix the cause and re-run
the publish job — `skip-existing` makes it skip whatever already landed. The
`Development Status` classifier in both `pyproject.toml` files is permanently
`5 - Production/Stable`; it is not bumped as part of any release.

1. Update the pre-release version examples in `README.md` and the docs
(grep the outgoing version — the pins live in the README Installation
section, `docs/index.md`, `docs/get-started/installation.md`, and `docs/get-started/real-host.md`) so the tagged
commit — and therefore the README PyPI publishes — names the version
being released. When entering a new phase (alpha → beta → rc), update
the banner wording too.
2. Check the full test matrix is green on the release commit. The publish
workflow re-runs the checks and blocks publishing until they pass, so a
red leg there means re-running the failed jobs on the Publishing run.
3. Create the release as a pre-release, passing the exact commit verified in
step 2 as `--target` (otherwise the tag is created from whatever `main`'s
HEAD is by then). The tagged commit determines everything about the
## Release lines

Two branches ship, and the package version comes from the git tag
(`uv-dynamic-versioning`). Publishing a GitHub release runs `publish-pypi.yml`
**from the tagged commit**, so the workflow that fires is the tagged branch's

@cubic-dev-ai cubic-dev-ai Bot Jul 26, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1: A v1.x release will use the default-branch release workflow, not a workflow definition from v1.x; current publish-pypi.yml therefore attempts to build mcp-types too. Document/configure a default-branch workflow that branches on the release tag (or use a supported separate trigger) before directing maintainers to cut v1 releases this way.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At RELEASE.md, line 14:

<comment>A `v1.x` release will use the default-branch release workflow, not a workflow definition from `v1.x`; current `publish-pypi.yml` therefore attempts to build `mcp-types` too. Document/configure a default-branch workflow that branches on the release tag (or use a supported separate trigger) before directing maintainers to cut v1 releases this way.</comment>

<file context>
@@ -7,63 +7,118 @@
+
+Two branches ship, and the package version comes from the git tag
+(`uv-dynamic-versioning`). Publishing a GitHub release runs `publish-pypi.yml`
+**from the tagged commit**, so the workflow that fires is the tagged branch's
+own: a `main` tag builds and publishes two distributions (`mcp` and
+`mcp-types`, lock-stepped via `Requires-Dist: mcp-types=={{ version }}`), and a
</file context>

own: a `main` tag builds and publishes two distributions (`mcp` and
`mcp-types`, lock-stepped via `Requires-Dist: mcp-types=={{ version }}`), and a
`v1.x` tag builds and publishes `mcp` only.

| Line | Branch | Tag | GitHub release flags |
| ---------------------------- | ------ | ------------------------- | ------------------------------------- |
| Current stable | `main` | `v2.X.Y` | not a pre-release; becomes **Latest** |
| Maintenance (previous major) | `v1.x` | `v1.28.Z` | not a pre-release; **not** Latest |
| Pre-releases | `main` | `v2.X.YaN` / `bN` / `rcN` | **Pre-release** ticked, never Latest |

The `Development Status` classifier in both `pyproject.toml` files is
permanently `5 - Production/Stable`; it is not bumped as part of any release.
The `mcp-types` PyPI project carries the same trusted publisher as `mcp` (this
repository, workflow `publish-pypi.yml`, environment `release`). For a release
cut from `main`, if only some of the four files upload, fix the cause and
re-run the publish job — its `skip-existing` setting makes it skip whatever
already landed (the `v1.x` workflow publishes a single distribution and has no
such setting).

## Stable release from `main` (`v2.X.Y`)

The stable line's README and docs carry no version pin (`pip install "mcp[cli]"`
installs the newest stable release), so a routine stable release needs no
pin-flip commit; the exception is the first stable release of a new major,
whose pre-release banner and pins are replaced by that flip. `README.md` at the
tagged commit is the PyPI long description, so any README fix has to merge
before the tag.

1. Check the full test matrix is green on the release commit. The publish
workflow re-runs the same checks and blocks publishing until they pass, so a
red leg there means re-running the failed jobs on the Publishing run — but
verify green before creating the release rather than discovering red after
the tag exists.
2. Freeze `main` from that commit until the tag exists: the release is created
with an explicit `--target`, and nothing else should land in between.
3. Create the release NOT as a pre-release, passing the verified commit as
`--target` (otherwise the tag is created from whatever `main`'s HEAD is by
then). It becomes GitHub "Latest", and PyPI's default `pip install mcp`
version moves to it. The tagged commit determines everything about the
release — the workflows that run and the package metadata (readme,
classifiers) that gets published — so it must contain the current release
tooling, not just pass tests. `--target` is ignored if the tag already
exists: when re-creating a release, delete the old tag first and
double-check where the new tag points. The pre-release flag keeps GitHub's
"Latest" badge and `/releases/latest` pointing at the stable v1.x line:
double-check where the new tag points.

```shell
gh release create v2.X.Y --title v2.X.Y --target <commit-sha> --notes-file <notes.md>
```

4. Curate the release notes: the highlights, anything known-incomplete, and
links to the docs and migration guide, above a `## What's Changed` list.
Generate that list with the release UI's "Generate release notes" (setting
its **Previous tag** to the previous release on this line by hand — the
auto-picked baseline is the newest tag, which may sit on the other line), or
assemble the whole body in the file passed to `--notes-file`. Use absolute
URLs (relative links don't resolve in GitHub release bodies).
5. If a stable release turns out to be broken, yank it on PyPI and release the
fix as the next patch version. Never delete a release from PyPI — version
numbers cannot be reused. Yank `mcp` and `mcp-types` together (they are one
release), and set the yank reason and the GitHub release notes to point at
the replacement version, since yanking doesn't stop `==` pins from installing
the broken version.
Comment on lines +71 to +76

@claude claude Bot Jul 27, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 The "ask someone to review the release" step now survives only in the lower-stakes v1.x maintenance section (line 93), while the new stable-from-main procedure — the one that takes GitHub "Latest" and moves PyPI's default pip install mcp, with mistakes fixable only by yank-plus-new-patch per step 5 — has no review step in any of its 5 steps. Consider adding the same sentence at the end of this section so the second-pair-of-eyes check covers the highest-stakes flow too.

Extended reasoning...

What happened. The pre-PR RELEASE.md ended its stable-release procedure ("Major or Minor Release") with "Then ask someone to review the release." After this rewrite, that sentence exists exactly once — at line 93, closing the Maintenance release from v1.x section. The new Stable release from main (v2.X.Y) section (lines 31–71) has no review step in any of its 5 steps.

Why this looks like an oversight, not a decision. One could argue the sentence simply stayed attached to the section it originally belonged to: the old stable procedure was the v1.x procedure, and its direct textual successor is the new maintenance section. That's mechanically true — but the review requirement was attached to the stable role, not to the v1.x branch as such: it closed the procedure for the release that takes GitHub "Latest" and PyPI's default install. After the flip, that role belongs to the v2-from-main cut, yet the safeguard didn't move with it. Two details in the new doc itself support the oversight reading: (1) the maintenance section frames itself as "create the release the same way with two differences" — and dropping the review step is not one of the listed differences, so the asymmetry isn't presented as intentional anywhere; (2) nothing in the PR description mentions removing the review requirement for stable releases.

Why it matters. The stable section's own step 5 explains why a pre-publish second pair of eyes is most valuable exactly here: never delete from PyPI, version numbers cannot be reused, and the only remedy for a broken stable release is yanking mcp and mcp-types together plus cutting the next patch. The failure modes the doc warns about — tagging the wrong commit (--target ignored when the tag exists), a stale README becoming the immutable PyPI long description, missing release tooling at the tagged commit — are all things a reviewer can catch before gh release create runs. The automated safeguards the new section adds (verify green, freeze main, explicit --target, publish workflow re-runs checks) all apply to both lines via the shared release environment, so none of them substitutes asymmetrically for the human review that now only the maintenance line gets.

Concrete walk-through. A maintainer cutting v2.1.0 reads only the stable section (it's named for their task). They follow steps 1–5: verify green, freeze main, run gh release create v2.1.0 --title v2.1.0 --target <sha> --notes-file notes.md, curate notes, done — no step tells them to have anyone look before or after publishing. Meanwhile a maintainer cutting v1.28.5 from the maintenance line is explicitly told "Then ask someone to review the release." The doc now requires more scrutiny for the release that can't even take "Latest" than for the one that moves pip install mcp for everyone.

Fix. Add "Then ask someone to review the release." (or an explicit review-before-publish step) at the end of the stable section, restoring parity with both the old doc's requirement and the maintenance section.

Severity. Nit: this is a docs-process omission — no code or automation is affected, and whether a v2 stable cut requires a second reviewer is ultimately a maintainer policy choice. It's a one-sentence fix that shouldn't block merge.


## Maintenance release from `v1.x` (`v1.28.Z`)

Land the `[v1.x]`-prefixed backport PRs (and any README banner update, which is
the README PyPI shows for that version), verify the branch tip green, then
create the release the same way with two differences:

- **The tag's target is the verified commit on the `v1.x` branch.** The UI and
CLI default the target to `main`, which is the v2 codebase — a v1 tag created
there would publish v2 code as a v1 stable release. Pass the exact commit
verified green in the previous step rather than the branch name, for the
same moving-HEAD reason as above.
- **It must not take "Latest" back from the 2.x line.** The UI ticks "Set as
the latest release" by default for the newest non-pre-release; untick it, or
pass `--latest=false`, and afterwards confirm `/releases/latest` still names
the newest v2 tag. If it slipped, `gh release edit v1.28.Z --latest=false`
fixes it — release metadata only, no re-cut.
Comment on lines +89 to +93

@claude claude Bot Jul 28, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 The maintenance section's post-release check — "confirm /releases/latest still names the newest v2 tag" — is literally unsatisfiable whenever the newest v2 tag is a pre-release (e.g. v2.1.0b1), which is the normal cadence this doc documents: pre-releases are never Latest, so /releases/latest correctly names an older stable while the check reads as failed. One-word fix: "newest v2 tag" → "newest stable v2 release", matching the pre-release section's own wording.

Extended reasoning...

The issue. The Maintenance section (RELEASE.md lines 82–86) instructs, after cutting v1.28.Z with --latest=false: "afterwards confirm /releases/latest still names the newest v2 tag." Taken literally, this verification check fails in the doc's own steady state — and the doc itself explains why.

Why the literal check is unsatisfiable. Two other parts of this same PR establish that /releases/latest can never name a pre-release: the Release lines table says pre-releases are "Pre-release ticked, never Latest", and pre-release step 3 says "The pre-release flag keeps GitHub's 'Latest' badge and /releases/latest on the newest stable release." Meanwhile, the doc's documented cadence ("Pre-releases of the next version are cut from main") means the newest v2 tag is routinely a pre-release tag between stables. So the newest v2 tag and the tag /releases/latest names are, by design, often different tags.

Step-by-step proof. (1) v2.0.0 is released stable from main and takes Latest. (2) v2.1.0b1 is tagged as a pre-release, per the Pre-releases section — /releases/latest correctly stays on v2.0.0. (3) A release manager cuts v1.28.Z per the Maintenance section, passing --latest=false as instructed. (4) They run the prescribed confirmation: /releases/latest returns v2.0.0. (5) The newest v2 tag, however, is v2.1.0b1 — so the literal check "still names the newest v2 tag" is not satisfied, even though every release flag is correct.

Why the offered remedy makes it worse. The next sentence says "If it slipped, gh release edit v1.28.Z --latest=false fixes it." In the scenario above, nothing slipped — --latest=false was already passed and the edit changes nothing. Nor is there any command that could make the literal check pass: GitHub refuses to mark a pre-release as Latest. The reader is left with a verification step that reports failure and a remedy that is a no-op.

Why this is an internal inconsistency, not a pedantic reading. The same document uses the precise wording where it matters: the pre-release section says the flag keeps /releases/latest "on the newest stable release", and step 4 of the stable section even warns that "the auto-picked baseline is the newest tag, which may sit on the other line" — the author clearly distinguishes tags from Latest-eligible releases elsewhere. The Maintenance check is the one place the distinction was dropped.

Impact and fix. Impact is limited to release-time confusion: the bolded rule ("must not take Latest back from the 2.x line") makes the intent recoverable — a reader seeing any stable v2 release at /releases/latest would likely move on. But a runbook verification step whose literal success condition is false in the documented normal state is a genuine wording defect. One-word fix: change "the newest v2 tag" to "the newest stable v2 release", matching the pre-release section's own phrasing.


```shell
gh release create v1.28.Z --title v1.28.Z --target <commit-sha> --latest=false --notes-file <notes.md>
```

When generating notes, set **Previous tag** to the previous `v1.*` release by
hand for the same reason as above. Then ask someone to review the release.

## Pre-releases from `main`

Pre-releases of the next version are cut from `main` with a PEP 440
pre-release tag: `aN` for alphas, later `bN`/`rcN` for betas and release
candidates. The PEP 440 suffix is what keeps `pip install mcp` on the stable
version — installers only select a pre-release when it is requested explicitly (an
exact pin, a specifier that names a pre-release version, or `--pre`).
Comment on lines +107 to +108

@cubic-dev-ai cubic-dev-ai Bot Jul 28, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: Dependency resolution can select a pre-release without an exact pin, pre-release-bearing specifier, or --pre when no final version satisfies its constraint. Qualify this as the normal/default behavior so release guidance does not promise an exclusion PEP 440 does not guarantee.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At RELEASE.md, line 107:

<comment>Dependency resolution can select a pre-release without an exact pin, pre-release-bearing specifier, or `--pre` when no final version satisfies its constraint. Qualify this as the normal/default behavior so release guidance does not promise an exclusion PEP 440 does not guarantee.</comment>

<file context>
@@ -97,8 +104,8 @@ hand for the same reason as above. Then ask someone to review the release.
 candidates. The PEP 440 suffix is what keeps `pip install mcp` on the stable
-version — installers only select a pre-release when it is requested by exact
-pin.
+version — installers only select a pre-release when it is requested explicitly (an
+exact pin, a specifier that names a pre-release version, or `--pre`).
 
</file context>
Suggested change
version — installers only select a pre-release when it is requested explicitly (an
exact pin, a specifier that names a pre-release version, or `--pre`).
version — installers normally exclude pre-releases, so `pip install mcp` stays
on the stable version.


1. During a pre-release phase the README and docs pin the exact pre-release
version, so update those examples first (grep the outgoing version — the
pins live in the README Installation section, `docs/index.md`,
`docs/get-started/installation.md`, and `docs/get-started/real-host.md`) so
the tagged commit — and therefore the README PyPI publishes — names the
version being released. When entering a new phase (alpha → beta → rc →
stable), update the banner wording too; the stable phase drops the pins.
2. Check the full test matrix is green on the release commit, as above.
3. Create the release as a pre-release, passing the verified commit as
`--target`. The pre-release flag keeps GitHub's "Latest" badge and
`/releases/latest` on the newest stable release:

```shell
gh release create v2.0.0aN --prerelease --title v2.0.0aN --target <commit-sha>
gh release create v2.X.YbN --prerelease --title v2.X.YbN --target <commit-sha>
```

4. Curate the release notes instead of relying on auto-generated ones: what
changed since the previous pre-release, what is known-incomplete, the
install line (`pip install mcp==2.0.0aN`), and a link to the migration
guide. Use the absolute URL
(`https://github.com/modelcontextprotocol/python-sdk/blob/main/docs/migration.md`)
because relative links don't resolve in GitHub release bodies.
5. If a pre-release turns out to be broken, yank it on PyPI and cut the next
one. Never delete a release from PyPI — version numbers cannot be reused.
Yanking doesn't stop `==` pins from installing the broken version, so set
the yank reason (and edit the GitHub release notes) to point at the
replacement version.
4. Curate the release notes: what changed since the previous pre-release, what
is known-incomplete, the install line (`pip install mcp==2.X.YbN`), and a
link to the migration guide, with absolute URLs.
5. If a pre-release turns out to be broken, yank both `mcp` and `mcp-types` on PyPI
and cut the next one, pointing the yank reason and the GitHub release notes
at the replacement version.
Loading