From 9bd0146c3a447a61cb71f12deaa35ec48074ffab Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 12 Jun 2026 22:25:59 +0000
Subject: [PATCH] feat(release-train): span stable release notes from the
 previous stable release

Stable graduations produced nearly-empty GitHub Release notes because the
work was attributed to the alpha/beta changelog entries and --unreleased
only covered the merge commits since the last beta tag. Stable releases
now generate their notes over <previous-stable>..HEAD with pre-release
tags ignored, yielding one flat section that describes everything landing
in production. Pre-releases keep the previous behavior.

https://claude.ai/code/session_01MFD8imoXtKUEUoZTvL5Ztv
---
 .github/workflows/docker-release.yml | 24 +++++++++++++++++++++++-
 README.md                            |  5 +++++
 2 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/docker-release.yml b/.github/workflows/docker-release.yml
index 85f6249..cc7bbdc 100644
--- a/.github/workflows/docker-release.yml
+++ b/.github/workflows/docker-release.yml
@@ -206,13 +206,35 @@ jobs:
           OUTPUT: CHANGELOG.md
           GITHUB_REPO: ${{ github.repository }}
 
+      # Stable releases accumulate everything shipped since the PREVIOUS
+      # stable release into a single flat section — the work that flowed
+      # through alpha/beta would otherwise be attributed to the pre-release
+      # entries and leave the stable notes nearly empty. Pre-releases keep
+      # covering only what is new since the last tag.
+      - name: Determine release notes range
+        if: steps.cliff_detect.outputs.present == 'true' && github.ref_name != 'develop'
+        id: notes_range
+        run: |
+          if [ "${{ inputs.release_type }}" = "stable" ]; then
+            PREV_STABLE=$(git tag -l 'v[0-9]*' --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -1 || true)
+            # The regex is single-quoted because git-cliff-action splices
+            # these args into a bash command line.
+            if [ -n "$PREV_STABLE" ]; then
+              echo "args=--ignore-tags '.*-(alpha|beta|rc).*' ${PREV_STABLE}..HEAD" >> "$GITHUB_OUTPUT"
+            else
+              echo "args=--ignore-tags '.*-(alpha|beta|rc).*'" >> "$GITHUB_OUTPUT"
+            fi
+          else
+            echo "args=--unreleased" >> "$GITHUB_OUTPUT"
+          fi
+
       - name: Generate release body fragment
         if: steps.cliff_detect.outputs.present == 'true' && github.ref_name != 'develop'
         id: cliff_body
         uses: orhun/git-cliff-action@v4
         with:
           config: cliff.toml
-          args: --verbose --unreleased --strip header --tag ${{ steps.bump.outputs.tag }}
+          args: --verbose --strip header --tag ${{ steps.bump.outputs.tag }} ${{ steps.notes_range.outputs.args }}
         env:
           OUTPUT: RELEASE_NOTES.md
           GITHUB_REPO: ${{ github.repository }}
diff --git a/README.md b/README.md
index ddd0fae..548510e 100644
--- a/README.md
+++ b/README.md
@@ -326,6 +326,11 @@ Duplicate tags are rejected before anything is published.
 This guarantees a git tag can never lag behind a published image, which is
 what previously allowed version reuse.
 
+**Release notes:** stable releases accumulate everything shipped since the
+previous stable release into one flat section (the work that flowed through
+alpha/beta), so the notes describe what actually lands in production.
+Pre-release notes only cover what is new since the last tag.
+
 **Usage (consumer repository):**
 
 ```yaml