ci(release): derive release notes from CHANGELOG.md (#52)

Previously `release.yml` ran `gh release create --generate-notes`, which
produces GitHub's raw PR-list auto-summary. OpenSSF BestPractices
`release_notes` explicitly disqualifies that form — release notes must
be a human-readable curated summary of major changes and upgrade impact.

This ties the release workflow to CHANGELOG.md as the single source:

  1. After artifact download, a new "Resolve release notes" step:
     - Looks for `## [vX.Y.Z]` or `## [X.Y.Z]` in CHANGELOG.md.
     - If missing, promotes non-empty `## [Unreleased]` → `## [X.Y.Z] — <today>`,
       inserts a fresh `## [Unreleased]` above it, commits the rename to
       main as github-actions[bot], and re-extracts.
     - If neither [Unreleased] nor [X.Y.Z] have content, fails with a
       clear instruction to populate CHANGELOG.md.
     - Emits the extracted section as a multi-line step output.

  2. The "Create GitHub release" step consumes that output via
     `--notes-file` (prepended to the existing cosign Verify footer).
     The old draft-then-edit dance is gone.

CHANGELOG.md gets a short contributor note explaining the flow so the
promotion is discoverable.

One acceptable consequence: the binary's embedded Commit SHA refers to
the pre-rename commit (github.sha captured by the build job), while the
tag points to the post-rename commit. The binary bytes are unaffected;
only the CHANGELOG.md doc differs.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: aksOps

.github/workflows/release.yml

@@ -159,6 +159,72 @@ jobs:
           pattern: binary-*
           path: downloaded/
 
+      - name: Resolve release notes from CHANGELOG.md
+        id: notes
+        env:
+          TAG: ${{ needs.tag.outputs.tag }}
+        run: |
+          set -eu
+
+          # Extract the block under `## [<heading>]` up to the next `## [` heading.
+          extract_section() {
+            awk -v h="$1" '
+              $0 ~ "^## \\[" h "\\]" { found=1; next }
+              found && /^## \[/           { exit }
+              found                       { print }
+            ' CHANGELOG.md
+          }
+
+          has_content() { printf '%s' "$1" | grep -Eq '[^[:space:]]'; }
+
+          # The tag arrives as vX.Y.Z; CHANGELOG convention is [X.Y.Z] (no v).
+          TAG_STRIPPED="${TAG#v}"
+
+          body=""
+          for candidate in "$TAG" "$TAG_STRIPPED"; do
+            body=$(extract_section "$candidate")
+            if has_content "$body"; then break; fi
+          done
+
+          if ! has_content "$body"; then
+            # Promote [Unreleased] → [TAG_STRIPPED] — YYYY-MM-DD and insert a fresh empty Unreleased.
+            unreleased=$(extract_section 'Unreleased')
+            if ! has_content "$unreleased"; then
+              echo "::error::CHANGELOG.md has neither a '## [${TAG}]' / '## [${TAG_STRIPPED}]' section nor a non-empty '## [Unreleased]' section."
+              echo "::error::Add a '## [${TAG_STRIPPED}] — YYYY-MM-DD' section (or populate Unreleased) before releasing."
+              exit 1
+            fi
+
+            echo "Promoting [Unreleased] → [${TAG_STRIPPED}] in CHANGELOG.md"
+            date_iso=$(date -u +%Y-%m-%d)
+            python3 - <<PY
+          import pathlib
+          p = pathlib.Path('CHANGELOG.md')
+          t = p.read_text()
+          needle = '## [Unreleased]'
+          replacement = f'## [Unreleased]\n\n## [${TAG_STRIPPED}] — ${date_iso}'
+          if needle not in t:
+              raise SystemExit("no '## [Unreleased]' heading in CHANGELOG.md")
+          p.write_text(t.replace(needle, replacement, 1))
+          PY
+
+            git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+            git config user.name  'github-actions[bot]'
+            git add CHANGELOG.md
+            git commit -m "docs: release ${TAG}"
+            git push origin HEAD:main
+
+            body=$(extract_section "$TAG_STRIPPED")
+          fi
+
+          # Emit to GITHUB_OUTPUT (heredoc form for multi-line).
+          {
+            echo 'body<<__RN_EOF__'
+            printf '%s' "$body"
+            echo
+            echo '__RN_EOF__'
+          } >> "$GITHUB_OUTPUT"
+
       - name: Assemble versioned binaries + SHA256SUMS
         env:
           TAG: ${{ needs.tag.outputs.tag }}
@@ -201,19 +267,11 @@ jobs:
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           TAG: ${{ needs.tag.outputs.tag }}
+          NOTES_BODY: ${{ steps.notes.outputs.body }}
         run: |
           set -eu
-          # Draft first so we can get the auto-generated body, then edit
-          # the body to append the cosign Verify footer before publishing.
-          gh release create "$TAG" \
-            --title "$TAG" \
-            --generate-notes \
-            --draft \
-            dist/docsiq-* dist/SHA256SUMS dist/SHA256SUMS.sig dist/SHA256SUMS.pem
-
-          body=$(gh release view "$TAG" --json body -q .body)
           {
-            printf '%s\n\n' "$body"
+            printf '%s\n\n' "$NOTES_BODY"
             printf '### Verify\n\n'
             printf 'All artifacts are signed with [cosign](https://github.com/sigstore/cosign) keyless via Sigstore.\n\n'
             printf '```sh\n'
@@ -226,7 +284,10 @@ jobs:
             printf '```\n'
           } > release-notes.md
 
-          gh release edit "$TAG" --notes-file release-notes.md --draft=false
+          gh release create "$TAG" \
+            --title "$TAG" \
+            --notes-file release-notes.md \
+            dist/docsiq-* dist/SHA256SUMS dist/SHA256SUMS.sig dist/SHA256SUMS.pem
 
       - name: Generate SLSA build provenance
         id: attest

CHANGELOG.md

@@ -10,6 +10,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 Each release ships signed binaries (cosign keyless + Rekor), a signed
 `SHA256SUMS`, and SLSA build provenance.
 
+> **Contributors:** add bullets under `## [Unreleased]` as part of any
+> PR worth mentioning in release notes. When the release workflow runs,
+> it promotes `[Unreleased]` → `[vX.Y.Z] — YYYY-MM-DD` automatically and
+> uses that section as the GitHub release body. If no non-empty
+> `[Unreleased]` section exists at release time, the workflow fails.
+
 ## [Unreleased]
 
 ### Added