@@ -359,140 +359,107 @@ package, its version PR (2b or 2c) runs again first.
359359### 5a. Draft the release notes
360360
361361Draft 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
385392REPO=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.
392396MERGE_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
498465The target is the SHA, so the tag lands on the commit the ledger verified,
0 commit comments