From b6dd16a3a8b00631e2755d7bb8c3849fc6decf8f Mon Sep 17 00:00:00 2001
From: github-actions <actions@github.com>
Date: Sat, 22 Aug 2026 14:26:04 +0200
Subject: [PATCH] fix: close the release.yml changelog race too

Same race as the docs one fixed in finalize-release.yml earlier:
release.yml is triggered asynchronously by the tag push and used to
generate CHANGELOG.md and commit it to main itself, after
finalize-release.yml had already merged main back into develop --
develop never received that commit. Confirmed happening on the v0.6.0
release: develop needed a manual post-hoc sync to pick up the
changelog commit.

Moved changelog generation into finalize-release.yml, synchronously,
right after tagging (so git-cliff picks up the new tag) and before
merging back into develop. release.yml no longer touches main -- it
just checks out the tip finalize-release.yml already updated and reads
the already-current CHANGELOG.md for its --latest release notes.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .github/workflows/finalize-release.yml | 31 ++++++++++++++++++++++++++
 .github/workflows/release.yml          | 18 ++++++---------
 2 files changed, 38 insertions(+), 11 deletions(-)

diff --git a/.github/workflows/finalize-release.yml b/.github/workflows/finalize-release.yml
index 34cbc22..5565869 100644
--- a/.github/workflows/finalize-release.yml
+++ b/.github/workflows/finalize-release.yml
@@ -16,6 +16,15 @@
 #   into develop, so develop is always caught up regardless of what
 #   code-docs.yml does on its own schedule.
 #
+# Changelog generation:
+#   release.yml (triggered separately by the tag push below) used to
+#   generate CHANGELOG.md and commit it to main itself — the same async
+#   race as the docs one above, just for a different file. Generating and
+#   committing it here instead, after tagging and before merging back into
+#   develop, means develop is caught up on the changelog too, and release.yml
+#   no longer needs to touch main at all — it just reads the already-current
+#   CHANGELOG.md for its release notes.
+#
 # Secrets required:
 #   APP_ID, APP_PRIVATE_KEY — GitHub App credentials, exchanged for a
 #   short-lived installation token scoped to this repo
@@ -100,6 +109,28 @@ jobs:
           git tag ${{ github.event.inputs.version }}
           git push origin ${{ github.event.inputs.version }}
 
+      - name: Install git-cliff
+        run: |
+          GITCLIFF_VERSION="2.13.0"
+          curl -L "https://github.com/orhun/git-cliff/releases/download/v${GITCLIFF_VERSION}/git-cliff-${GITCLIFF_VERSION}-x86_64-unknown-linux-gnu.tar.gz" -o git-cliff.tar.gz
+          tar xzf git-cliff.tar.gz
+          sudo mv "git-cliff-${GITCLIFF_VERSION}/git-cliff" /usr/local/bin/git-cliff
+          rm -rf git-cliff.tar.gz "git-cliff-${GITCLIFF_VERSION}"
+          git-cliff --version
+
+      - name: Generate CHANGELOG.md
+        run: git-cliff --config .cliff.toml --output CHANGELOG.md
+
+      - name: Commit and push changelog
+        run: |
+          git add CHANGELOG.md
+          if ! git diff-index --quiet HEAD; then
+            git commit -m "chore(release): update changelog for ${{ github.event.inputs.version }}"
+            git push origin main
+          else
+            echo "No changelog changes to commit"
+          fi
+
       - name: Merge main back into develop
         run: |
           git checkout develop
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 9c24b10..5f8ff7b 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -26,22 +26,18 @@ jobs:
               rm -rf git-cliff.tar.gz "git-cliff-${GITCLIFF_VERSION}"
               git-cliff --version
 
+        # CHANGELOG.md is generated and committed by finalize-release.yml,
+        # synchronously, before it merges main back into develop -- doing it
+        # there instead of here closes a race where this workflow (triggered
+        # asynchronously by the tag push) used to commit the changelog to
+        # main after finalize-release.yml had already synced develop,
+        # leaving develop permanently missing that commit. Checking out main
+        # here just gets onto the tip finalize-release.yml already updated.
         - name: Checkout main
           run: |
               git checkout main
               git pull origin main
 
-        - name: Generate CHANGELOG.md
-          run: git-cliff --config .cliff.toml --output CHANGELOG.md
-
-        - name: Commit changelog
-          run: |
-              git config user.name "github-actions"
-              git config user.email "actions@github.com"
-              git add CHANGELOG.md
-              git commit -m "chore(release): update changelog for ${{ github.ref_name }}" || echo "No changes"
-              git push origin main
-
         - name: Generate release notes
           run: git-cliff --config .cliff.toml --latest --output RELEASE_NOTES.md