fix: close the release.yml changelog race too

.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

.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