From bbac2194c94b49adb83fde4f35ffbdf4c75cb170 Mon Sep 17 00:00:00 2001
From: "Y.D.X." <73375426+YDX-2147483647@users.noreply.github.com>
Date: Wed, 7 Jan 2026 17:34:41 +0800
Subject: [PATCH] ci: Improve release notes for pre-releases

---
 .github/workflows/release.yml | 13 ++++++++++++-
 cliff.toml                    | 14 +++++++++++++-
 2 files changed, 25 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 38a047e4..4ed7616b 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -182,10 +182,21 @@ jobs:
         id: git-cliff
         with:
           config: cliff.toml
-          args: -vv ${{ github.event.release.prerelease && '--unreleased' || '--latest' }} --strip header
+          # Partially override cliff.toml to generate better release notes.
+          # - For public releases, show changes since the last _public_ release.
+          # - For pre-releases, show changes since the last release (either public or pre-release).
+          # - For testing (workflow_dispatch), show changes not belonging to any release.
+          args: >-
+            -vv
+            --strip header
+            ${{ github.event_name == 'release' && '--current' || '--unreleased' }}
+            ${{ github.event_name == 'release' && (github.event.release.prerelease && '--ignore-tags ""' || '--tag-pattern ''^v\d+\.\d+\.\d+$''') }}
         env:
           OUTPUT: CHANGES.md
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Write release notes to the job summary
+        run: |
+          cat CHANGES.md >> "$GITHUB_STEP_SUMMARY"
 
       - uses: actions/checkout@v6
 
diff --git a/cliff.toml b/cliff.toml
index 9db8bfa0..e2e85eea 100644
--- a/cliff.toml
+++ b/cliff.toml
@@ -26,9 +26,21 @@ body = """
   https://github.com/{{ remote.github.owner }}/{{ remote.github.repo }}
 {%- endmacro -%}
 
-{% if version %}\
+{#- Same as git.ignore_tags in cliff.toml, but won't be overridden from CLI -#}
+{%- set ignore_tags = ".*alpha|beta|-.*" -%}
+
+{% if version and version is not matching(ignore_tags) %}\
+    {#- when generating CHANGELOG.md or release notes for _public_ releases #}\
     ## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d", timezone="Asia/Shanghai") }}
+{% elif version %}\
+    {#- when generating release notes for _pre_-releases #}\
+    ## [unreleased]
+
+    The following are new unreleased changes \
+    introduced in [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d", timezone="Asia/Shanghai") }} \
+    compared to [{{ previous.version | trim_start_matches(pat="v") }}] - {{ previous.timestamp | date(format="%Y-%m-%d", timezone="Asia/Shanghai") }}.
 {% else %}\
+    {#- when testing #}\
     ## [unreleased]
 {% endif %}\
 {% for group, commits in commits | unique(attribute="id") | group_by(attribute="group") %}