Skip to content

Commit 2f4b115

Browse files
authored
Merge pull request #5283 from modelcontextprotocol/v2/chore/5250-release-notes-thanks
release:notes: credit advisory reporters and by-hand contributors in the Thanks section
2 parents 877ef2f + 535d20b commit 2f4b115

4 files changed

Lines changed: 822 additions & 44 deletions

File tree

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

Lines changed: 45 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -526,11 +526,25 @@ what changed in the server they use:
526526
judgment, so it is written by hand, never generated.
527527
7. **`## Thanks for helping us improve`**: one list for the whole release, as
528528
the Inspector's release notes have it, crediting the community members
529-
whose issues the listed PRs close, one line per person, most issues first.
529+
whose issues the listed PRs close and whose advisories (`--advisory`) the
530+
release fixes, one line per person, most references first; then the
531+
prototype paragraph, one line per `--thank`.
530532
531533
GitHub adds everyone `@`-mentioned in a release body to that release's
532534
**Contributors** strip, so the people credited appear there too.
533535

536+
**Collect both kinds of credit the helper cannot find on its own before the
537+
preview**, since the generator writes the whole Thanks section and nothing is
538+
added to the draft by hand:
539+
540+
- **Every advisory this release fixes**, as `--advisory GHSA-xxxx-yyyy-zzzz`,
541+
once each: the `[GHSA-…]` cards on the board for the milestone's work
542+
(`security-advisory`). Its fix shipped from a private fork with no public
543+
issue, so its reporters are no issue's author. A draft advisory works.
544+
- **Every outside contributor credited on one of the milestone's issues**, as
545+
`--thank "@login (#PR), <what it prototyped>, for #ISSUE"`, once per line
546+
of the prototype paragraph. The preview lists each candidate (below).
547+
534548
Preview first. The default run prints the notes and creates nothing:
535549
536550
```sh
@@ -545,20 +559,34 @@ git fetch origin main && git rev-parse "$MERGE_SHA^{tree}" # must be the tree
545559
NOTES=$(mktemp)
546560
npm run --silent release:notes -- --milestone "$MILESTONE" --merge-sha "$MERGE_SHA" \
547561
--merge-branch "v2/chore/$N-release-$MILESTONE" --ledger-url "<the ledger's URL>" \
562+
--advisory GHSA-xxxx-yyyy-zzzz --thank "@login (#PR), <what>, for #ISSUE" \
548563
> "$NOTES"; echo "EXIT=$?"
549564
```
550565

551566
Add `--known-issue "<markdown>"` once per known issue. The helper reads the
552567
manifests at `$MERGE_SHA` from GitHub, so it needs no checkout of that
553568
commit. It takes a few minutes: it looks up every listed PR's files and
554-
closing issues, and every reporter's permission.
569+
closing issues, every reporter's permission, and, in a preview, every
570+
comment on the milestone's closed issues.
571+
572+
**Read the preview before going on**, and its standard error with it:
555573

556-
**Read the preview before going on.** Then create the draft with the same
557-
arguments plus `--draft`:
574+
- **`credit notes on <milestone>'s closed issues`** lists every credit a
575+
maintainer left on one of them (an issue body or comment saying "credit" or
576+
"thanks to" and naming a non-maintainer), each person marked
577+
`(--thank given)` or `(NO --thank)`. Add a `--thank` for each one marked
578+
`NO` whose prototype ships in this release, and re-run the preview. A note
579+
that only credits a reporter the list already has needs none.
580+
- **`PENDING advisory credit`** names a credit its recipient has not accepted
581+
yet. It is listed, and may still be declined: settle it with the reporter
582+
(`security-advisory`) before publishing, or re-run once they answer.
583+
584+
Then create the draft with the same arguments plus `--draft`:
558585

559586
```sh
560587
npm run --silent release:notes -- --milestone "$MILESTONE" --merge-sha "$MERGE_SHA" \
561-
--merge-branch "v2/chore/$N-release-$MILESTONE" --ledger-url "<the ledger's URL>" --draft
588+
--merge-branch "v2/chore/$N-release-$MILESTONE" --ledger-url "<the ledger's URL>" \
589+
--advisory GHSA-xxxx-yyyy-zzzz --thank "@login (#PR), <what>, for #ISSUE" --draft
562590
```
563591

564592
`--draft` creates a **draft** Release tagged `$MILESTONE` at `$MERGE_SHA`. It
@@ -582,14 +610,21 @@ The rules the helper applies:
582610
- **Maintainers and bots are excluded by permission, not by name.** A
583611
maintainer is anyone with `admin`, `maintain` or `write` on the repo. Bots,
584612
deleted accounts, PR numbers and other repos' issues are dropped.
585-
- **Outside PRs are credited through their issue, by hand.** This repo
613+
- **An advisory's credits are read from the advisory**, accepted and pending
614+
ones, any credit type. A declined credit, a bot and a maintainer are
615+
dropped. An advisory in `triage` (not accepted), `closed` or `withdrawn`
616+
aborts the run: it has no fix in this release to credit.
617+
- **Outside PRs are credited through their issue, with `--thank`.** This repo
586618
closes an outside PR and files an issue for a fix worth keeping, crediting
587619
the PR's author in that issue (`issue-triage`, Harvest). The helper credits
588-
the issue's *author*, who is then a maintainer and is excluded. Read the
589-
milestone's issues for such credits and add those people to the draft's
590-
Thanks section by hand before publishing.
620+
the issue's *author*, who is then a maintainer and is excluded, so the
621+
credit comes from a `--thank`, and the preview's discovery list is what
622+
shows which ones are still missing. Discovery only reads notes a maintainer
623+
wrote; a community member offering a fix in a comment is credited when a
624+
maintainer says so on the issue.
591625
- **"Addresses", not "fixes."** The credited issues include feature requests.
592-
- **The Thanks section is left out** when no community reporter remains.
626+
- **The Thanks section is left out** when nobody is credited: no community
627+
reporter, no advisory credit and no `--thank`.
593628
- **It fails fast.** A failed `gh` call, a GraphQL error, a missing PR or
594629
issue, an unknown permission value, a generated line it does not recognize,
595630
or a registry answer other than 200 or 404 aborts the run before anything is

‎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). [`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.
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 and advisories (`--advisory`) the release addresses and whose prototypes ship in it (`--thank`), 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

0 commit comments

Comments
 (0)