Skip to content

Commit 68ca87e

Browse files
maxisbeymaxisbey
authored
Document the two-line release process for stable v2 (#3179)
1 parent c9c431b commit 68ca87e

1 file changed

Lines changed: 114 additions & 52 deletions

File tree

‎RELEASE.md‎

Lines changed: 114 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -7,63 +7,125 @@
77
`[tool.hatch.metadata.hooks.uv-dynamic-versioning].dependencies`.
88
2. Upgrade lock with `uv lock --resolution lowest-direct`
99

10-
## Major or Minor Release
11-
12-
Stable releases are cut from the `v1.x` branch. Create a GitHub release via UI
13-
with the tag being `vX.Y.Z` where `X.Y.Z` is the version and the release title
14-
being the same, and **set the tag's target to the `v1.x` branch** — the UI
15-
defaults to `main`, which is the v2 rework, and a v1 tag created there would
16-
publish the v2 codebase as a stable release. Then ask someone to review the
17-
release.
18-
19-
The package version will be set automatically from the tag.
20-
21-
## v2 Pre-releases
22-
23-
v2 pre-releases are cut from `main` with a PEP 440 pre-release tag: `v2.0.0aN`
24-
for alphas, later `bN`/`rcN` for betas and release candidates.
25-
26-
A release publishes two distributions, `mcp` and `mcp-types`, at the same
27-
version, and the `mcp` wheel exact-pins `mcp-types`. Before the first release
28-
that includes both, the `mcp-types` PyPI project must be given the same
29-
trusted publisher as `mcp` (this repository, workflow `publish-pypi.yml`,
30-
environment `release`) and the same owners — without it the `mcp-types`
31-
upload is rejected. If only some of the files upload, fix the cause and re-run
32-
the publish job — `skip-existing` makes it skip whatever already landed. The
33-
`Development Status` classifier in both `pyproject.toml` files is permanently
34-
`5 - Production/Stable`; it is not bumped as part of any release.
35-
36-
1. Update the pre-release version examples in `README.md` and the docs
37-
(grep the outgoing version — the pins live in the README Installation
38-
section, `docs/index.md`, `docs/get-started/installation.md`, and `docs/get-started/real-host.md`) so the tagged
39-
commit — and therefore the README PyPI publishes — names the version
40-
being released. When entering a new phase (alpha → beta → rc), update
41-
the banner wording too.
42-
2. Check the full test matrix is green on the release commit. The publish
43-
workflow re-runs the checks and blocks publishing until they pass, so a
44-
red leg there means re-running the failed jobs on the Publishing run.
45-
3. Create the release as a pre-release, passing the exact commit verified in
46-
step 2 as `--target` (otherwise the tag is created from whatever `main`'s
47-
HEAD is by then). The tagged commit determines everything about the
10+
## Release lines
11+
12+
Two branches ship, and the package version comes from the git tag
13+
(`uv-dynamic-versioning`). Publishing a GitHub release runs `publish-pypi.yml`
14+
**from the tagged commit**, so the workflow that fires is the tagged branch's
15+
own: a `main` tag builds and publishes two distributions (`mcp` and
16+
`mcp-types`, lock-stepped via `Requires-Dist: mcp-types=={{ version }}`), and a
17+
`v1.x` tag builds and publishes `mcp` only.
18+
19+
| Line | Branch | Tag | GitHub release flags |
20+
| ---------------------------- | ------ | ------------------------- | ------------------------------------- |
21+
| Current stable | `main` | `v2.X.Y` | not a pre-release; becomes **Latest** |
22+
| Maintenance (previous major) | `v1.x` | `v1.28.Z` | not a pre-release; **not** Latest |
23+
| Pre-releases | `main` | `v2.X.YaN` / `bN` / `rcN` | **Pre-release** ticked, never Latest |
24+
25+
The `Development Status` classifier in both `pyproject.toml` files is
26+
permanently `5 - Production/Stable`; it is not bumped as part of any release.
27+
The `mcp-types` PyPI project carries the same trusted publisher as `mcp` (this
28+
repository, workflow `publish-pypi.yml`, environment `release`). For a release
29+
cut from `main`, if only some of the four files upload, fix the cause and
30+
re-run the publish job — its `skip-existing` setting makes it skip whatever
31+
already landed (the `v1.x` workflow publishes a single distribution and has no
32+
such setting).
33+
34+
## Stable release from `main` (`v2.X.Y`)
35+
36+
The stable line's README and docs carry no version pin (`pip install "mcp[cli]"`
37+
installs the newest stable release), so a routine stable release needs no
38+
pin-flip commit; the exception is the first stable release of a new major,
39+
whose pre-release banner and pins are replaced by that flip. `README.md` at the
40+
tagged commit is the PyPI long description, so any README fix has to merge
41+
before the tag.
42+
43+
1. Check the full test matrix is green on the release commit. The publish
44+
workflow re-runs the same checks and blocks publishing until they pass, so a
45+
red leg there means re-running the failed jobs on the Publishing run — but
46+
verify green before creating the release rather than discovering red after
47+
the tag exists.
48+
2. Freeze `main` from that commit until the tag exists: the release is created
49+
with an explicit `--target`, and nothing else should land in between.
50+
3. Create the release NOT as a pre-release, passing the verified commit as
51+
`--target` (otherwise the tag is created from whatever `main`'s HEAD is by
52+
then). It becomes GitHub "Latest", and PyPI's default `pip install mcp`
53+
version moves to it. The tagged commit determines everything about the
4854
release — the workflows that run and the package metadata (readme,
4955
classifiers) that gets published — so it must contain the current release
5056
tooling, not just pass tests. `--target` is ignored if the tag already
5157
exists: when re-creating a release, delete the old tag first and
52-
double-check where the new tag points. The pre-release flag keeps GitHub's
53-
"Latest" badge and `/releases/latest` pointing at the stable v1.x line:
58+
double-check where the new tag points.
59+
60+
```shell
61+
gh release create v2.X.Y --title v2.X.Y --target <commit-sha> --notes-file <notes.md>
62+
```
63+
64+
4. Curate the release notes: the highlights, anything known-incomplete, and
65+
links to the docs and migration guide, above a `## What's Changed` list.
66+
Generate that list with the release UI's "Generate release notes" (setting
67+
its **Previous tag** to the previous release on this line by hand — the
68+
auto-picked baseline is the newest tag, which may sit on the other line), or
69+
assemble the whole body in the file passed to `--notes-file`. Use absolute
70+
URLs (relative links don't resolve in GitHub release bodies).
71+
5. If a stable release turns out to be broken, yank it on PyPI and release the
72+
fix as the next patch version. Never delete a release from PyPI — version
73+
numbers cannot be reused. Yank `mcp` and `mcp-types` together (they are one
74+
release), and set the yank reason and the GitHub release notes to point at
75+
the replacement version, since yanking doesn't stop `==` pins from installing
76+
the broken version.
77+
78+
## Maintenance release from `v1.x` (`v1.28.Z`)
79+
80+
Land the `[v1.x]`-prefixed backport PRs (and any README banner update, which is
81+
the README PyPI shows for that version), verify the branch tip green, then
82+
create the release the same way with two differences:
83+
84+
- **The tag's target is the verified commit on the `v1.x` branch.** The UI and
85+
CLI default the target to `main`, which is the v2 codebase — a v1 tag created
86+
there would publish v2 code as a v1 stable release. Pass the exact commit
87+
verified green in the previous step rather than the branch name, for the
88+
same moving-HEAD reason as above.
89+
- **It must not take "Latest" back from the 2.x line.** The UI ticks "Set as
90+
the latest release" by default for the newest non-pre-release; untick it, or
91+
pass `--latest=false`, and afterwards confirm `/releases/latest` still names
92+
the newest v2 tag. If it slipped, `gh release edit v1.28.Z --latest=false`
93+
fixes it — release metadata only, no re-cut.
94+
95+
```shell
96+
gh release create v1.28.Z --title v1.28.Z --target <commit-sha> --latest=false --notes-file <notes.md>
97+
```
98+
99+
When generating notes, set **Previous tag** to the previous `v1.*` release by
100+
hand for the same reason as above. Then ask someone to review the release.
101+
102+
## Pre-releases from `main`
103+
104+
Pre-releases of the next version are cut from `main` with a PEP 440
105+
pre-release tag: `aN` for alphas, later `bN`/`rcN` for betas and release
106+
candidates. The PEP 440 suffix is what keeps `pip install mcp` on the stable
107+
version — installers only select a pre-release when it is requested explicitly (an
108+
exact pin, a specifier that names a pre-release version, or `--pre`).
109+
110+
1. During a pre-release phase the README and docs pin the exact pre-release
111+
version, so update those examples first (grep the outgoing version — the
112+
pins live in the README Installation section, `docs/index.md`,
113+
`docs/get-started/installation.md`, and `docs/get-started/real-host.md`) so
114+
the tagged commit — and therefore the README PyPI publishes — names the
115+
version being released. When entering a new phase (alpha → beta → rc →
116+
stable), update the banner wording too; the stable phase drops the pins.
117+
2. Check the full test matrix is green on the release commit, as above.
118+
3. Create the release as a pre-release, passing the verified commit as
119+
`--target`. The pre-release flag keeps GitHub's "Latest" badge and
120+
`/releases/latest` on the newest stable release:
54121

55122
```shell
56-
gh release create v2.0.0aN --prerelease --title v2.0.0aN --target <commit-sha>
123+
gh release create v2.X.YbN --prerelease --title v2.X.YbN --target <commit-sha>
57124
```
58125

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

0 commit comments

Comments
 (0)