From 3710cadebafbcff4dd60b97544f63b2e3b69c029 Mon Sep 17 00:00:00 2001
From: keithlostracco <keith@actualize.vision>
Date: Sat, 25 Jul 2026 16:20:49 -0700
Subject: [PATCH] ci: build release notes from CHANGELOG and skip publishing
 without a tag

Releases were published with an empty description: the workflow passed
no body and did not ask GitHub to generate notes, so every set of notes
so far has been written by hand after the fact.

The release body now comes from the CHANGELOG entry matching the tag,
with GitHub's generated 'What's Changed' section appended. Tagging a
version that has no changelog entry fails the release instead of
publishing a blank description.

The release job is also gated on refs/tags/*. A release cannot be
published from a branch, so a manual workflow_dispatch run always failed
at the final step with 'GitHub Releases requires a tag'. It now skips
publishing and serves as a dry run of the build and test gate.

The extraction was tested against every section in CHANGELOG.md,
including the last one, and against a version with no entry.
---
 .github/workflows/release.yml | 28 ++++++++++++++++++++++++++++
 CHANGELOG.md                  |  7 +++++++
 2 files changed, 35 insertions(+)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 82542be..fca8353 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -58,7 +58,12 @@ jobs:
       run: ctest -C Release --output-on-failure
 
   # Package a single source archive and publish the release.
+  #
+  # Only runs for tag pushes. A release cannot be published from a branch, so on
+  # workflow_dispatch this job is skipped and the workflow acts as a dry run of
+  # the cross-platform build and test gate above.
   release:
+    if: startsWith(github.ref, 'refs/tags/')
     needs: build
     runs-on: ubuntu-latest
     permissions:
@@ -71,10 +76,33 @@ jobs:
     - name: Package source archive
       run: zip -r anim-${{ github.ref_name }}-src.zip include src cmake CMakeLists.txt README.md LICENSE CONTRIBUTING.md CHANGELOG.md
 
+    # Use the CHANGELOG entry for this tag as the release body, so the notes are
+    # written once and reviewed in the pull request that introduced them.
+    - name: Extract release notes from CHANGELOG
+      run: |
+        version="${GITHUB_REF_NAME#v}"
+        awk -v v="$version" '
+          $0 ~ "^## \\[" v "\\]" { found = 1; next }   # heading for this version
+          found && /^## \[/       { exit }             # next version heading
+          found && /^\[.*\]: /    { exit }             # link reference block
+          found && /^<!--/        { exit }             # trailing comments
+          found                   { print }
+        ' CHANGELOG.md \
+          | sed -e '/./,$!d' -e :a -e '/^\n*$/{$d;N;};/\n$/ba' > RELEASE_NOTES.md
+
+        if [ ! -s RELEASE_NOTES.md ]; then
+          echo "::error::CHANGELOG.md has no '## [$version]' section. Add one before tagging $GITHUB_REF_NAME." >&2
+          exit 1
+        fi
+        echo "Release notes for $version:"
+        cat RELEASE_NOTES.md
+
     - name: Create Release
       uses: softprops/action-gh-release@v3
       with:
         files: anim-${{ github.ref_name }}-src.zip
         name: Release ${{ github.ref_name }}
+        body_path: RELEASE_NOTES.md
+        generate_release_notes: true
         draft: false
         prerelease: false
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3b28390..dbcc8d1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -36,6 +36,13 @@ conventions; both are mechanical find-and-replace changes for callers.
 - CI now builds with CMake 4.4. The `windows-latest` runner image ships Visual
   Studio 2026, for which a generator first exists in CMake 4.2; the previously
   pinned CMake 3.26 fell back to NMake and could not find a compiler at all.
+- Releases now take their description from this file's entry for the tag, with
+  GitHub's generated notes appended, instead of being published with an empty
+  body and filled in by hand. Tagging a version with no changelog entry now
+  fails the release rather than publishing a blank description.
+- The release workflow no longer fails when started manually. Publishing needs
+  a tag, so on `workflow_dispatch` it skips the publish step and runs purely as
+  a dry run of the cross-platform build and test gate.
 
 ### Added