--- name: release-notes description: Write release notes for a tagged release — a business-impact summary of what changed for the user, plus a thanks section naming every contributor whose commits are in the release. Short by construction. --- # Release notes Turn one release (a tag, or a range of commits) into notes a reader skims in under a minute: what the release does for them, stated as impact, and a thank- you to everyone whose work is in it. Not a changelog, not a commit list. Three rules, in priority order: 1. **Lead with business impact, not mechanism.** Every line answers "what does this change let me do / stop worrying about," not "what file moved." Group by the value to the reader, not by subsystem. Drop anything a user never sees (CI wiring, test-only changes, internal refactors) unless it changed a guarantee they rely on. 2. **Thank every contributor whose commits are in the release** (see below). Completeness here is not optional — a missing name is the one error people notice. 3. **Short.** If a section is not impact or thanks, cut it. No methodology hedging, no "we're excited to", no filler. A reader should reach the end without scrolling twice. ## Step 1 — establish the exact range, then read it Never write from memory or from a PR list. Read the real commits. - Find the previous release tag and this one: `git tag --sort=-creatordate | head`. - List the commits: `git log .. --format='%h %an%x09%s'`. (If there is no tag yet, use `..HEAD` and say so.) - Verify both endpoints resolve (`git rev-parse `), and that the range is non-empty. An empty range means the wrong tags — stop and fix it. Read every subject line. Cluster them by what the user gets. A cluster of five commits that together fix one thing is ONE bullet about that thing. ## Step 2 — write the impact, and claim only what the range establishes For each cluster, write one line of impact. Constraints: - State only what the commits actually did. If you cannot point to the commit that establishes a claim, do not make the claim. No numbers without a source you can name (a command, a file). If you quote a measurement, say where it was measured. - Platform coverage and signing, when relevant, are stated plainly and honestly — what is signed, what is not, and what the user must do about it. Never imply a signature or an auto-update path that does not exist. - Keep the project's own voice. Do not add a tagline the project has not adopted; if it has a pinned one, use it verbatim and do not reword it. - Banned, because they read as machine-written or as marketing haze: "verbatim", "delve", "seamless", "robust", "we're thrilled/excited", "leverage" (as a verb), "in today's fast-paced". Say the plain thing instead. ## Step 3 — the thanks section: every contributor, once, by handle The contributors are the distinct **authors** of the commits in the range — the AUTHOR, never the committer (many projects normalise the committer to one maintainer identity, so the committer tells you nothing about who wrote it). 1. List the authoring commits: `git log .. --format='%H%x09%an%x09%ae'`. 2. **Resolve each commit to a GitHub handle authoritatively — do NOT parse the email.** An email does not reliably encode the handle: a GitHub noreply address like `103962359+L4XB@users.noreply.github.com` happens to embed the login, but a personal address like `rahulpamula123@gmail.com` embeds nothing, and the login is not the display name (author `Rahul-pamula` with that email is handle `Rahul-pamula`, whose CLA ledger file is `rahul-pamula.md` — a dash and a case the email never shows). Get the login from the forge instead: `gh api repos///commits/ --jq '.author.login'` per commit (or `.commit.author` cross-checked against the PR that landed it). That is the handle; the email is only a hint you must confirm. 3. **Also enumerate co-authors — the author query cannot see them.** `%an/%ae` and the commits API each return exactly ONE author per commit; a `Co-authored-by:` trailer (used for pairing, and by some squash-merges to credit a second person) is invisible to both. Read them explicitly: `git log .. --format='%(trailers:key=Co-authored-by,valueonly)'`, which yields `Name ` lines. Resolve each to a handle the same way as a primary author (by the ledger, or a forge lookup on the email) and add it to the set. Do not skip this because "we don't use trailers" — verify it on the range; a single co-authored commit crediting an external is a name you would otherwise drop. 4. Remove the maintainer/release identity and any bots (`dependabot[bot]`, `github-actions[bot]`, and the maintainer's own login) from the combined set of primary authors and co-authors. What remains is the external contributors. 5. **Deduplicate to one person.** The same human appears under multiple author identities in one range (a noreply email on one commit, a personal email on another; a display name and a login) — e.g. `Prince Panchani` and `PrinceXDev` are one person, handle `PrinceXDev`. Collapse by resolved handle, not by email or name, so each person is thanked exactly once. 6. If the project keeps a CLA ledger (`contributors/.md` — the filename IS the handle, lowercased), confirm each resolved handle has a matching ledger file and print it in the ledger's spelling. The CLA gate guarantees every external author has a ledger entry, so a resolved author with no ledger match means your handle resolution is wrong (you parsed the email, or missed a dash/case), not that they are unlisted — re-resolve that author's handle (list item 2 above), do not drop them. Without a ledger, and when a commit's `.author.login` comes back `null` (the commit email is tied to no GitHub account), resolve the person by the `Name ` from `git show -s --format='%an <%ae>'` and, if you still cannot get a handle, name them by that display name rather than dropping them — a missing contributor is worse than an un-linked one. 7. Verify by UNION, not by recounting one query. The distinct people you print must equal the deduped union of {primary-author handles} ∪ {co-author handles} ∪ {any commit whose author login was null}, minus maintainer/bots. Do NOT re-derive the check from the same `%ae` set you thanked from — a count built from the query that already dropped the co-authors and the null-logins will "confirm" a list that is missing exactly them. Recompute each input set independently and compare. Write the section as a plain thank-you naming each `@handle`, separated so it scans (e.g. `·`-joined on one line, or a short list). One sentence of context is enough; do not explain the contribution model at length. ## Step 4 — self-review before you hand it over - Every impact line: is it true of the code in this range, and is it impact (not mechanism)? - Thanks: re-run the author query and confirm every distinct external person is present exactly once, spelled as their real handle. - Length: could a reader skim it in under a minute? If not, cut. - Then have it independently reviewed before it ships — release notes are outward-facing text, and a false or missing claim there is the expensive kind. ## Shape (adapt; keep it short) ``` — . ## Fixed / Added / Changed (only the sections you actually have) **.** … ## ## Thanks , then: @handle · @handle · @handle ```