From 3b375a9eeb92b1d3199ea98b712e8c69db635658 Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Tue, 22 Sep 2026 21:59:16 +0200 Subject: [PATCH] docs(release-process): put the credit into a CHANGELOG-extracted body's source Some release workflows extract the new version's CHANGELOG section with sed and publish it as the release body; netresearch/terraform-provider-ad does. That body carries exactly the @mentions the CHANGELOG entries carry, and that repository's entries credit nobody, so every release there fails release-notes-status.sh with MISSING CREDITS until the published body is edited by hand. v0.5.3 was never edited and still contains no @mention at all (checked 2026-09-22); v0.5.4 needed the hand edit the same day. The section on crediting contributors now says to write the credit into the CHANGELOG entry, so the extraction publishes it, and to add it with gh release edit for a release already out. Assisted-by: claude-code:claude-opus-5-5 Agent-Session: https://claude.ai/code/session_01GY5RqMQzgKbEvCALQ7r1ec Agent-Host: 0493f0 Signed-off-by: Sebastian Mendel --- CHANGELOG.md | 1 + skills/github-release/references/release-process.md | 2 ++ 2 files changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 138ef20..9febeb9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,7 @@ their notes were not backfilled here rather than reconstructed after the fact. - the release-safety checkpoint and the release-process checkpoint distinguish the two flows: a workflow-published release, and a tag-only repository where the release is created by hand against the pushed signed tag - `references/supply-chain-security.md` records that the SLSA generic generator cannot run under the `sha_pinning_required` ruleset: `generator_generic_slsa3.yml` at `v2.1.0` — the latest release, 2025-02-24 — calls four nested actions by tag, and the run is rejected at the first of them. Pinning the generator's own `uses:` does not help, the references are inside it. The page names `actions/attest-build-provenance` as what to use there, and says to state the level actually reached rather than the one the workflow is named after - `SKILL.md`, `references/release-process.md`, `references/immutable-releases.md`, `README.md`, `AGENTS.md` and both release commands state the rule as "never without `--verify-tag`" rather than "never", and name which of the two flows a repository is in as something to establish from its workflows +- `references/release-process.md` says where the credit goes when the release workflow builds the body from `CHANGELOG.md`: into the CHANGELOG entry, because the extracted body carries only the `@mentions` the entries carry. Without them every such release fails `release-notes-status.sh` with `MISSING CREDITS` until someone edits the published body by hand ### Fixed diff --git a/skills/github-release/references/release-process.md b/skills/github-release/references/release-process.md index 0e93c8a..2a00930 100644 --- a/skills/github-release/references/release-process.md +++ b/skills/github-release/references/release-process.md @@ -266,6 +266,8 @@ gh api repos/owner/repo/compare/... --jq '.commits[].author.login?' | The compare API caps at 250 commits — for a wider range, run it in two halves. +**Where the release workflow builds the body from `CHANGELOG.md`, the credit belongs in the CHANGELOG entry.** Some workflows extract the new version's section with `sed` and publish it as the body — `netresearch/terraform-provider-ad` does. Such a body carries exactly the `@mentions` its CHANGELOG entries carry. If the entries credit nobody, every release fails `release-notes-status.sh` with `MISSING CREDITS` and needs a hand edit after publishing, and a release nobody edits stays uncredited: that repository's v0.5.3 still is. Write the credit into the entry itself — `([#43](https://github.com/owner/repo/pull/43) by @login)` — so the extraction publishes it. For a release already out without it, add the credit with `gh release edit --notes-file`, and credit the next entries in the CHANGELOG. + #### Narrative over implementation details Release notes are for the people deciding whether to upgrade — users, admins, integrators — not for developers reading the diff. Lead with the user-facing story, then brief feature sections.