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.