Skip to content

Commit 76075f2

Browse files
committed
Address review nits in the release process doc
Scope the partial-upload re-run advice to releases cut from main (the v1.x publisher has no skip-existing setting), note that the first stable release of a major still needs its pre-release flip, spell out how the generated What's Changed list is produced, target the verified commit rather than the branch name for a v1.x release, describe pre-release selection accurately, and yank both packages when a pre-release is bad. No-Verification-Needed: doc-only
1 parent 8ba2305 commit 76075f2

1 file changed

Lines changed: 28 additions & 21 deletions

File tree

RELEASE.md

Lines changed: 28 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -25,16 +25,20 @@ own: a `main` tag builds and publishes two distributions (`mcp` and
2525
The `Development Status` classifier in both `pyproject.toml` files is
2626
permanently `5 - Production/Stable`; it is not bumped as part of any release.
2727
The `mcp-types` PyPI project carries the same trusted publisher as `mcp` (this
28-
repository, workflow `publish-pypi.yml`, environment `release`). If only some
29-
of the four files upload, fix the cause and re-run the publish job —
30-
`skip-existing` makes it skip whatever already landed.
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).
3133

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

3436
The stable line's README and docs carry no version pin (`pip install "mcp[cli]"`
35-
installs the newest stable release), so a stable release needs no pin-flip
36-
commit. `README.md` at the tagged commit is the PyPI long description, so any
37-
README fix has to merge before the tag.
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.
3842

3943
1. Check the full test matrix is green on the release commit. The publish
4044
workflow re-runs the same checks and blocks publishing until they pass, so a
@@ -57,12 +61,13 @@ README fix has to merge before the tag.
5761
gh release create v2.X.Y --title v2.X.Y --target <commit-sha> --notes-file <notes.md>
5862
```
5963

60-
4. Curate the release notes above the auto-generated `## What's Changed` list:
61-
the highlights, anything known-incomplete, and links to the docs and
62-
migration guide. Use absolute URLs (relative links don't resolve in GitHub
63-
release bodies), and set the generated list's **Previous tag** to the
64-
previous release on this line by hand — the auto-picked baseline is the
65-
newest tag, which may sit on the other line.
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).
6671
5. If a stable release turns out to be broken, yank it on PyPI and release the
6772
fix as the next patch version. Never delete a release from PyPI — version
6873
numbers cannot be reused. Yank `mcp` and `mcp-types` together (they are one
@@ -76,17 +81,19 @@ Land the `[v1.x]`-prefixed backport PRs (and any README banner update, which is
7681
the README PyPI shows for that version), verify the branch tip green, then
7782
create the release the same way with two differences:
7883

79-
- **The tag's target is the `v1.x` branch.** The UI and CLI default the target
80-
to `main`, which is the v2 codebase — a v1 tag created there would publish v2
81-
code as a v1 stable release.
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.
8289
- **It must not take "Latest" back from the 2.x line.** The UI ticks "Set as
8390
the latest release" by default for the newest non-pre-release; untick it, or
8491
pass `--latest=false`, and afterwards confirm `/releases/latest` still names
8592
the newest v2 tag. If it slipped, `gh release edit v1.28.Z --latest=false`
8693
fixes it — release metadata only, no re-cut.
8794

8895
```shell
89-
gh release create v1.28.Z --title v1.28.Z --target v1.x --latest=false --notes-file <notes.md>
96+
gh release create v1.28.Z --title v1.28.Z --target <commit-sha> --latest=false --notes-file <notes.md>
9097
```
9198

9299
When generating notes, set **Previous tag** to the previous `v1.*` release by
@@ -97,8 +104,8 @@ hand for the same reason as above. Then ask someone to review the release.
97104
Pre-releases of the next version are cut from `main` with a PEP 440
98105
pre-release tag: `aN` for alphas, later `bN`/`rcN` for betas and release
99106
candidates. The PEP 440 suffix is what keeps `pip install mcp` on the stable
100-
version — installers only select a pre-release when it is requested by exact
101-
pin.
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`).
102109

103110
1. During a pre-release phase the README and docs pin the exact pre-release
104111
version, so update those examples first (grep the outgoing version — the
@@ -119,6 +126,6 @@ pin.
119126
4. Curate the release notes: what changed since the previous pre-release, what
120127
is known-incomplete, the install line (`pip install mcp==2.X.YbN`), and a
121128
link to the migration guide, with absolute URLs.
122-
5. If a pre-release turns out to be broken, yank it on PyPI and cut the next
123-
one, pointing the yank reason and the GitHub release notes at the
124-
replacement version.
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)