Skip to content

Commit 24d7ed5

Browse files
committed
Merge remote-tracking branch 'origin/v2/main' into v2/feat/4874-issue-filing-sweeps
Signed-off-by: cliffhall <[email protected]> # Conflicts: # AGENTS.md
2 parents acbae35 + 7e751ec commit 24d7ed5

6 files changed

Lines changed: 1749 additions & 111 deletions

File tree

‎.claude/skills/release/SKILL.md‎

Lines changed: 75 additions & 108 deletions
Original file line numberDiff line numberDiff line change
@@ -359,140 +359,107 @@ package, its version PR (2b or 2c) runs again first.
359359
### 5a. Draft the release notes
360360

361361
Draft these once the merge PR has merged, so `main` holds what is being
362-
released. Drafting creates nothing on GitHub; the maintainer publishes (5b).
363-
364-
The notes have five parts, in this order:
365-
366-
1. **Packages.** What this release publishes and at which version. The tag is
367-
the milestone's name, not a version, and seven packages carry seven
368-
versions, so the notes are where a reader finds them.
369-
2. **What's Changed.** GitHub's generated list of every PR since the previous
370-
release.
371-
3. **The release-ledger line**, linking the artifact from 4d.
372-
4. **`## Known issues`**, only when there is one. It names the issue, who is
362+
released. [`scripts/release-notes.mjs`](../../../scripts/release-notes.mjs)
363+
(`npm run release:notes`) builds them; its header says why each part is
364+
there. The changes are laid out per package, because a reader wants to know
365+
what changed in the server they use:
366+
367+
1. **`## Packages`.** Every package on the merge commit, its version, and
368+
whether this release publishes it (the registry does not have that version
369+
yet) or leaves it unchanged. The tag is the milestone's name, not a
370+
version, so this table is where a reader finds the versions.
371+
2. **One `## <package> <version>` section per published package**, whose
372+
`### What's Changed` lists the PRs that change files under its
373+
`src/<dir>/`. A PR that touches several servers is listed under each.
374+
3. **`## Repository`**: every PR no published section took (CI, docs, skills,
375+
a server whose version did not change), so no PR in the generated list is
376+
dropped.
377+
4. GitHub's **New Contributors** block and **Full Changelog** link, verbatim.
378+
5. **The release-ledger line**, linking the artifact from 4d.
379+
6. **`## Known issues`**, only when you pass one. It names the issue, who is
373380
affected and the workaround. What counts as a known issue is a maintainer's
374381
judgment, so it is written by hand, never generated.
375-
5. **`## Thanks for helping us improve`.** Credit to the community members
376-
whose issues the release addresses. GitHub adds everyone `@`-mentioned in a
377-
release body to that release's **Contributors** strip, so the people
378-
credited here appear there too.
382+
7. **`## Thanks for helping us improve`**: one list for the whole release, as
383+
the Inspector's release notes have it, crediting the community members
384+
whose issues the listed PRs close, one line per person, most issues first.
385+
386+
GitHub adds everyone `@`-mentioned in a release body to that release's
387+
**Contributors** strip, so the people credited appear there too.
379388

380-
The generated list comes from the same API the UI's *Generate release notes*
381-
button uses, so it can be produced without creating anything. The recipe below
382-
builds parts 1, 2 and 5, in a scratch directory outside the checkout.
389+
Preview first. The default run prints the notes and creates nothing:
383390

384391
```sh
385392
REPO=modelcontextprotocol/servers
386-
NOTES=$(mktemp -d)
387-
git fetch origin main --tags
388-
389393
# The commit being released is the merge PR's merge commit, by SHA. `main` is
390394
# a moving name: if anything else landed on it since, "main" would be a tree
391-
# the ledger never saw. Everything below targets the SHA.
395+
# the ledger never saw.
392396
MERGE_SHA=$(gh pr view <MERGE_PR> --repo "$REPO" --json mergeCommit --jq .mergeCommit.oid) || MERGE_SHA=
393397
[ -n "$MERGE_SHA" ] || echo "the merge PR has no merge commit: stop" >&2
394-
git rev-parse "$MERGE_SHA^{tree}" # must be the tree hash the ledger recorded
395-
396-
# The previous release is the latest PUBLISHED Release, asked of GitHub rather
397-
# than sorted out of the tag list: this repo's tags mix date stamps
398-
# (2026.8.31), milestone names (vX.Y.Z) and older per-package tags, and no
399-
# sort orders them correctly.
400-
PREV=$(gh release view --repo "$REPO" --json tagName --jq .tagName) || PREV=
401-
[ -n "$PREV" ] || echo "no previous release found: stop, do not guess one" >&2
402-
echo "$PREV → $MILESTONE" # sanity-check both
403-
404-
# 1. Packages: each one's name and version on main, and whether this release
405-
# publishes it. (HTTP 200 from the registry means that version is already
406-
# there, so this release skips it.)
407-
{
408-
echo "## Packages"
409-
echo
410-
echo "| Package | Version | Registry | In this release |"
411-
echo "| --- | --- | --- | --- |"
412-
node scripts/release-manifest.mjs | jq -r '
413-
(.npm | to_entries[] | [.value.name, .value.version, "npm"]),
414-
(.pypi | to_entries[] | [.value.name, .value.version, "PyPI"]) | @tsv' \
415-
| while IFS=$'\t' read -r name version registry; do
416-
case "$registry" in
417-
npm) url="https://registry.npmjs.org/$(printf %s "$name" | sed 's|/|%2F|')/$version" ;;
418-
PyPI) url="https://pypi.org/pypi/$name/$version/json" ;;
419-
esac
420-
code=$(curl -s -o /dev/null -w '%{http_code}' "$url")
421-
case "$code" in
422-
200) state="unchanged" ;;
423-
404) state="**published**" ;;
424-
*) state="UNKNOWN (HTTP $code): check by hand" ;;
425-
esac
426-
echo "| \`$name\` | \`$version\` | $registry | $state |"
427-
done
428-
} > "$NOTES/packages.md"
429-
430-
# 2. What's Changed, exactly as the UI generates it.
431-
gh api "repos/$REPO/releases/generate-notes" -f tag_name="$MILESTONE" \
432-
-f target_commitish="$MERGE_SHA" -f previous_tag_name="$PREV" --jq .body > "$NOTES/changed.md"
433-
434-
# 5. Reporter credit: the author of every issue a listed PR closes, minus
435-
# maintainers (admin/maintain/write) and bots.
436-
for pr in $(grep -oE 'pull/[0-9]+' "$NOTES/changed.md" | cut -d/ -f2 | sort -un); do
437-
gh api graphql -F n="$pr" -f query='query($n:Int!){repository(owner:"modelcontextprotocol",name:"servers"){pullRequest(number:$n){body closingIssuesReferences(first:20){nodes{number}}}}}' \
438-
--jq '.data.repository.pullRequest | ([.closingIssuesReferences.nodes[].number] + ([.body | scan("(?i)(?:closes|fixes|resolves) #([0-9]+)") | .[0] | tonumber])) | .[]'
439-
done | sort -un | while read -r n; do
440-
gh api graphql -F n="$n" -f query='query($n:Int!){repository(owner:"modelcontextprotocol",name:"servers"){issueOrPullRequest(number:$n){... on Issue{number author{login __typename}}}}}' \
441-
--jq '.data.repository.issueOrPullRequest | select(.number and .author.__typename == "User") | "\(.author.login) \(.number)"'
442-
done | while read -r who n; do
443-
perm=$(gh api "repos/$REPO/collaborators/$who/permission" --jq .permission 2>/dev/null || echo none)
444-
case "$perm" in admin|maintain|write) ;; *) echo "$who $n" ;; esac
445-
done | awk '{ c[$1]++; l[$1] = l[$1] (l[$1] ? ", " : "") "#" $2 }
446-
END { for (u in c) printf "%d\t%s\t%s\n", c[u], u, l[u] }' \
447-
| sort -t$'\t' -k1,1nr -k2,2f | awk -F'\t' '{ print "* @" $2 " (" $3 ")" }' > "$NOTES/thanks.txt"
448-
449-
: > "$NOTES/thanks.md" # truncate first, so a rerun never keeps a stale section
450-
[ -s "$NOTES/thanks.txt" ] && { printf '\n## Thanks for helping us improve\n\nThis release addresses issues reported by these community members. Thank you for taking the time to file them:\n\n'; cat "$NOTES/thanks.txt"; } >> "$NOTES/thanks.md"
451-
452-
# Assemble. Parts 3 and 4 are added by hand, between changed.md and thanks.md.
453-
cat "$NOTES/packages.md" <(echo) "$NOTES/changed.md" "$NOTES/thanks.md" > "$NOTES/release-notes.md"
454-
echo "$NOTES/release-notes.md"
398+
git fetch origin main && git rev-parse "$MERGE_SHA^{tree}" # must be the tree hash the ledger recorded
399+
400+
NOTES=$(mktemp)
401+
npm run --silent release:notes -- --milestone "$MILESTONE" --merge-sha "$MERGE_SHA" \
402+
--merge-branch "v2/chore/$N-release-$MILESTONE" --ledger-url "<the ledger's URL>" \
403+
> "$NOTES"; echo "EXIT=$?"
455404
```
456405

457-
Run the Packages step from a checkout of `$MERGE_SHA` (the verification
458-
worktree, moved there with `git switch --detach "$MERGE_SHA"`, will do), since
459-
it reads the manifests on disk.
406+
Add `--known-issue "<markdown>"` once per known issue. The helper reads the
407+
manifests at `$MERGE_SHA` from GitHub, so it needs no checkout of that
408+
commit. It takes a few minutes: it looks up every listed PR's files and
409+
closing issues, and every reporter's permission.
460410

461-
Then add the ledger line and any known issue, and **read the result before
462-
handing it over**. The rules behind the recipe:
411+
**Read the preview before going on.** Then create the draft with the same
412+
arguments plus `--draft`:
463413

414+
```sh
415+
npm run --silent release:notes -- --milestone "$MILESTONE" --merge-sha "$MERGE_SHA" \
416+
--merge-branch "v2/chore/$N-release-$MILESTONE" --ledger-url "<the ledger's URL>" --draft
417+
```
418+
419+
`--draft` creates a **draft** Release tagged `$MILESTONE` at `$MERGE_SHA`. It
420+
refuses a SHA that is not on `main`, and a tag that already has a Release or
421+
draft (edit or delete that one instead). Every run, preview included, refuses
422+
a milestone tag that already exists: GitHub would build the notes and the
423+
Release from that tag's commit, not `$MERGE_SHA`. There is no `--publish`: publishing
424+
starts `release.yml`, so it is the maintainer's act in 5b.
425+
426+
The rules the helper applies:
427+
428+
- **The previous release is the latest published Release**, asked of GitHub
429+
rather than sorted out of the tag list: this repo's tags mix date stamps
430+
(`2026.8.31`), milestone names (`vX.Y.Z`) and older per-package tags, and no
431+
sort orders them. `--previous-tag` overrides it in a preview only.
464432
- **An issue counts when a listed PR closes it**, through either the explicit
465433
closing link (`closingIssuesReferences`, which every PR here gets from
466434
`addCloseIssueReferences`) or a `Closes / Fixes / Resolves #N` in the PR
467435
body. So an issue older than the release still counts when this release
468436
closed it.
469437
- **Maintainers and bots are excluded by permission, not by name.** A
470-
maintainer is anyone with `admin`, `maintain` or `write` on the repo. Bot
471-
authors are dropped. On a public repo, anyone without a role reads as
472-
`read`, so they are credited.
473-
- **Outside PRs are credited through their issue.** This repo closes an
474-
outside PR and files an issue for a fix worth keeping, crediting the PR's
475-
author in that issue. The recipe credits the issue's *author*, who is then a
476-
maintainer and is excluded. Read the milestone's issues for such credits and
477-
add those people to the Thanks section by hand.
438+
maintainer is anyone with `admin`, `maintain` or `write` on the repo. Bots,
439+
deleted accounts, PR numbers and other repos' issues are dropped.
440+
- **Outside PRs are credited through their issue, by hand.** This repo
441+
closes an outside PR and files an issue for a fix worth keeping, crediting
442+
the PR's author in that issue (`issue-triage`, Harvest). The helper credits
443+
the issue's *author*, who is then a maintainer and is excluded. Read the
444+
milestone's issues for such credits and add those people to the draft's
445+
Thanks section by hand before publishing.
478446
- **"Addresses", not "fixes."** The credited issues include feature requests.
479-
- **Leave the section out** when no community reporter remains.
480-
- **`UNKNOWN` in the Packages table is a stop**, not a row to publish: a
481-
registry that did not answer says nothing about what will be released.
447+
- **The Thanks section is left out** when no community reporter remains.
448+
- **It fails fast.** A failed `gh` call, a GraphQL error, a missing PR or
449+
issue, an unknown permission value, a generated line it does not recognize,
450+
or a registry answer other than 200 or 404 aborts the run before anything is
451+
created. Re-run it; never patch around a failure by hand.
482452

483453
### 5b. Tag and publish
484454

485-
**A maintainer does this**, after the merge PR has merged. Through the GitHub
486-
UI: *Releases → Draft a new release → Choose a tag → type the milestone's name
487-
(`vX.Y.Z`) → Create new tag on publish*. For **Target**, pick the merge commit
488-
(`$MERGE_SHA` from 5a) under *Recent Commits*, not the branch `main`, then
489-
paste the notes from 5a and publish.
490-
491-
The same thing from the CLI, with the notes file from 5a:
455+
**A maintainer does this**, after reading the draft 5a created. The draft
456+
already carries the tag name (`vX.Y.Z`), the target (`$MERGE_SHA`, not the
457+
branch `main`) and the notes; publishing creates the tag. Through the GitHub
458+
UI: *Releases → the `vX.Y.Z` draft → Edit → Set as the latest release →
459+
Publish release*. From the CLI:
492460

493461
```sh
494-
gh release create "$MILESTONE" --repo modelcontextprotocol/servers \
495-
--target "$MERGE_SHA" --title "$MILESTONE" --notes-file "$NOTES/release-notes.md" --latest
462+
gh release edit "$MILESTONE" --repo modelcontextprotocol/servers --draft=false --latest
496463
```
497464

498465
The target is the SHA, so the tag lands on the commit the ledger verified,

‎AGENTS.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -54,8 +54,8 @@ servers/
5454
├── .changeset/ Pending changesets for the TypeScript servers, and the changesets config
5555
├── scripts/ The pre-push gate (gate-lease, smoke-servers, validate-py, coverage-py), its guards (verify-*),
5656
│ the skills tooling, release tooling (npm-publish-guard, prepare-python-release,
57-
│ pack-and-verify, release-manifest), and the issue-filing sweeps (dependency-refresh,
58-
│ dependabot-alerts, sdk-watch)
57+
│ pack-and-verify, release-manifest, release-notes), and the issue-filing sweeps
58+
│ (dependency-refresh, dependabot-alerts, sdk-watch)
5959
├── docs/ Design documents; quality-gate.md is the gate's reference (stages, CI vs local, the lease);
6060
│ contribution-model.md holds the outside-PR backlog plan; ai-software-factory.md is the
6161
│ overview of how the rules, skills, gates and sweeps fit together

‎RELEASING.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,7 @@ A release ships one **milestone**. The step-by-step procedure, with its commands
8383
A milestone that touches both languages and needs an audit fix has all three. They are merged before the next step starts.
8484
3. **The merge PR** takes `v2/main` into `main`. It is a pure merge: its branch is `origin/v2/main` with no commits of its own, and the merged tree equals `origin/v2/main`'s. Its body starts with `Part of #<release issue>`, not `Closes`, because `main` is the default branch and a closing keyword there would close the issue before anything is published. It is merged with a merge commit, never squashed.
8585
4. **The release ledger** is linked from the merge PR. It records, for the merge branch's tree: `npm run local:gate`; `npm run pack:verify` for each package; each server-facing issue in the milestone exercised through a client; and a targeted probe for each issue with no client surface. The maintainers approve the merge on it. A finding is fixed on `v2/main` and merged in again, never committed to the merge branch.
86-
5. **A maintainer publishes a GitHub Release** targeting the merge commit on `main` (the commit the ledger verified, chosen by SHA rather than by the branch name, which may have moved): Releases → Draft a new release → create a tag named for the milestone (`vX.Y.Z`) → paste the drafted notes → Publish. The tag is a label, not a version.
86+
5. **A maintainer publishes a GitHub Release** targeting the merge commit on `main` (the commit the ledger verified, chosen by SHA rather than by the branch name, which may have moved). [`scripts/release-notes.mjs`](scripts/release-notes.mjs) (`npm run release:notes`) writes the notes, one section per published package with its PRs and a Thanks section for the community members whose issues the release addresses, and with `--draft` creates the draft Release under a tag named for the milestone (`vX.Y.Z`). The maintainer reads the draft and publishes it. The tag is a label, not a version.
8787
6. **The build jobs run, then the maintainer approves the `release` environment deployments.** Each package publishes if its version is not on the registry yet; the rest skip cleanly.
8888
7. **The release issue is closed by hand**, and its card moves to Done.
8989

‎package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@
4444
"verify:dco": "node scripts/verify-dco.mjs",
4545
"smoke": "node scripts/smoke-servers.mjs",
4646
"pack:verify": "node scripts/pack-and-verify.mjs",
47+
"release:notes": "node scripts/release-notes.mjs",
4748
"local:gate": "node scripts/gate-lease.mjs npm run local:gate:stages",
4849
"local:gate:stages": "npm run verify:install-fresh && npm run verify:dco && npm run validate && npm run coverage && npm run validate:py && npm run coverage:py && npm run verify:skills:cli && npm run smoke"
4950
},

0 commit comments

Comments
 (0)