ci: Improve release notes for pre-releases

.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
 

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") %}