From a2c53a197f18f074a7dd421f20b015948022fcb1 Mon Sep 17 00:00:00 2001
From: Filipe Forattini <filipeforattini1@gmail.com>
Date: Fri, 31 Jul 2026 07:36:27 -0300
Subject: [PATCH] fix(release): stop shipping an empty changelog on the
 tag-push route
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

v0.3.1's release notes went out with no entries at all and a self-referential
`compare/v0.3.1...v0.3.1` link.

`--unreleased` means "commits belonging to no tag". On the tag-push route the
tag already points at HEAD when the workflow runs, so nothing is unreleased and
git-cliff renders an empty body. v0.3.0 escaped this only because it came
through workflow_dispatch. Resolve an explicit <prev>..<tag> range instead, and
keep --unreleased solely for the case where the tag does not exist yet.

The compare link was broken independently: cliff.toml emitted
`{{ previous.version }}...{{ version }}` verbatim, but the two callers disagree
on the `v` prefix — release-plz passes `0.3.2`, release.yml passes `v0.3.2`
(which is why the heading already trims it). Tags carry the `v`, so the
release-plz half produced 404s. Normalise both sides, then re-add the `v`.

Also warn when the generated changelog has no entries: v0.3.1 shipped one and
nothing anywhere said so.
---
 .github/workflows/release.yml | 35 ++++++++++++++++++++++++++++++++++-
 cliff.toml                    |  9 +++++++--
 2 files changed, 41 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 5212613..0811b3c 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -361,16 +361,49 @@ jobs:
           path: release
           merge-multiple: true
 
+      # `--unreleased` means "commits belonging to no tag". On the tag-push route
+      # the tag already points at HEAD by the time this runs, so nothing is
+      # unreleased and the notes come out empty — which is exactly what shipped
+      # in v0.3.1. Resolve an explicit <prev>..<tag> range instead, and only fall
+      # back to --unreleased when the tag genuinely does not exist yet (the
+      # workflow_dispatch route, where release-plz tags before dispatching).
+      - name: Resolve the changelog range
+        id: range
+        env:
+          TAG: ${{ needs.plan.outputs.release_tag }}
+        run: |
+          set -euo pipefail
+          if git rev-parse -q --verify "refs/tags/${TAG}" >/dev/null; then
+            PREV="$(git describe --tags --abbrev=0 "${TAG}^" 2>/dev/null || true)"
+            if [[ -n "$PREV" ]]; then
+              ARGS="${PREV}..${TAG}"
+            else
+              ARGS="--tag ${TAG}"   # first ever release: no predecessor
+            fi
+          else
+            ARGS="--unreleased --tag ${TAG}"
+          fi
+          echo "resolved git-cliff range args: ${ARGS}"
+          echo "args=${ARGS}" >> "$GITHUB_OUTPUT"
+
       - name: Generate changelog from commits
         uses: orhun/git-cliff-action@v4
         id: changelog
         with:
           config: cliff.toml
-          args: --unreleased --tag ${{ needs.plan.outputs.release_tag }} --strip header
+          args: ${{ steps.range.outputs.args }} --strip header
         env:
           OUTPUT: release-changelog.md
           GITHUB_REPO: ${{ github.repository }}
 
+      # An empty changelog is not a fatal condition, but it is always a bug —
+      # v0.3.1 shipped one and nothing said so.
+      - name: Warn on an empty changelog
+        run: |
+          if [[ ! -s release-changelog.md ]] || ! grep -qE '^\s*-' release-changelog.md; then
+            echo "::warning::the generated changelog has no entries — check the range resolved above"
+          fi
+
       - name: Compose release body
         env:
           TAG: ${{ needs.plan.outputs.release_tag }}
diff --git a/cliff.toml b/cliff.toml
index aee994d..d66b02a 100644
--- a/cliff.toml
+++ b/cliff.toml
@@ -20,8 +20,13 @@ body = """
 - {% if commit.scope %}**{{ commit.scope }}**: {% endif %}{{ commit.message | split(pat="\n") | first | trim }}
 {% endfor %}
 {% endfor -%}
-{% if previous and previous.version %}
-**Full Changelog**: https://github.com/reddb-io/dit/compare/{{ previous.version }}...{{ version }}
+{% if previous and previous.version and previous.version != version %}
+{# Our tags carry a `v` prefix, but the two callers disagree on whether the
+   rendered version does: release-plz passes a bare `0.3.2` while release.yml
+   passes the tag `v0.3.2` (hence the trim on the heading above). Emitting
+   either verbatim produces a 404 in one of the two — `compare/0.3.1...0.3.2`
+   was the broken half. Normalise, then re-add the `v` the tags actually use. #}
+**Full Changelog**: https://github.com/reddb-io/dit/compare/v{{ previous.version | trim_start_matches(pat="v") }}...v{{ version | trim_start_matches(pat="v") }}
 {% endif %}
 """