no-human-ai/no_human/release-notes

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.

1. 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.

1. 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 <prev-tag>..<this-tag> --format='%h %an%x09%s'.

(If there is no tag yet, use <prev-tag>..HEAD and say so.)

• Verify both endpoints resolve (git rev-parse <tag>), 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 <prev-tag>..<this-tag> --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/<owner>/<repo>/commits/<sha> --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.

1. 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 <prev-tag>..<this-tag> --format='%(trailers:key=Co-authored-by,valueonly)', which yields Name <email> 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.

1. 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.

1. 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.

1. If the project keeps a CLA ledger (contributors/<handle>.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 <email> 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.

1. 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)

<product> <version> — <platforms in one clause>.
 
<one or two lines: the headline of the release, as impact.>
 
## Fixed / Added / Changed   (only the sections you actually have)
**<impact, bold lead>.** <one or two sentences, plain.>
…
 
## <Signing / install, if the release changes it, stated plainly>
 
## Thanks
<one sentence>, then: @handle · @handle · @handle