alex/club-3090
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(changelog): automate CHANGELOG + release notes from commits via cliff (Option A)

Browse Source 
CHANGELOG.md is now auto-generated from commit messages by git-cliff in
the release workflow. Hand-edits below the static header will be wiped on
the next tag.

Workflow (`.github/workflows/release.yml`):
  - On tag push (`v[0-9]+.[0-9]+.[0-9]+`):
    1. Render GitHub Release body: `git-cliff --latest --strip header`
       → just the per-version section, no SemVer preamble repeat
    2. Regenerate full CHANGELOG.md: `git-cliff` (default = all tags)
       → preserves header + all historical sections
    3. Commit CHANGELOG.md back to master with `[skip ci]` marker
    4. Publish GitHub Release with the latest-only body

Template (`cliff.toml`):
  - `[changelog].header` now holds the SemVer preamble + CalVer→SemVer
    mapping table (preserved across regens; stripped from GitHub Release
    bodies via `--strip header`).
  - `body` template now renders the **full commit message** (subject as
    bold bullet, body indented below) instead of just the first line.
    Rich narrative I write in commit message bodies (tables, validation
    numbers, before/after diffs) now flows into both CHANGELOG.md and the
    GitHub Release page from the same source.
  - Per-release Pin/Diff footer guarded with `{% if version %}` so the
    Unreleased section doesn't emit empty links.

CHANGELOG.md replaced with the auto-gen output. Past hand-written tables
and phase breakdowns are replaced by the corresponding commit messages
(those were already rich for commits that mattered — v0.3.1 soak-helper
fix has its Before/After table in the commit body and renders fine).

Going forward: just write rich commit messages and tag. Both surfaces
update automatically. No hand-edit of CHANGELOG.md required.
This commit is contained in:
noonghunna
2026-05-10 20:53:51 +00:00
parent 83bf73d3ec
commit 64b0474a62
3 changed files with 8785 additions and 467 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/release.yml
+40 -3
View File
@@ -16,17 +16,54 @@ jobs:
uses: actions/checkout@v4
with:
fetch-depth: 0 # full history needed for git-cliff
token: ${{ secrets.GITHUB_TOKEN }}
- name: Generate release notes
id: cliff
# ---- (1) Generate the GitHub Release body (latest only, no header) ----
# `--strip header` drops the static SemVer preamble so the release page
# shows just the per-version section, while CHANGELOG.md (below) keeps
# the header at the top of the file.
- name: Generate release notes (latest only)
id: cliff-release
uses: orhun/git-cliff-action@v4
with:
config: cliff.toml
args: --latest --github-repo noonghunna/club-3090
args: --latest --strip header --github-repo noonghunna/club-3090
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
OUTPUT: RELEASE_NOTES.md
# ---- (2) Regenerate full CHANGELOG.md (all tags, with header) ----
- name: Regenerate CHANGELOG.md
uses: orhun/git-cliff-action@v4
with:
config: cliff.toml
args: --github-repo noonghunna/club-3090
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
OUTPUT: CHANGELOG.md
# ---- (3) Commit the regenerated CHANGELOG.md back to master ----
# The tag's commit doesn't include this auto-regen — but the GitHub
# Release page is correct (step 1), and master's CHANGELOG.md catches
# up ~1 min after tag push. Skipped if nothing changed.
- name: Commit CHANGELOG.md back to master
run: |
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
git fetch origin master
git checkout -B master origin/master
# Re-run cliff against master HEAD so the regen reflects what master
# actually contains (the tag may not yet be on master if pushed from
# a feature branch; uncommon but handled).
git add CHANGELOG.md
if git diff --staged --quiet; then
echo "CHANGELOG.md unchanged — skipping commit."
else
git commit -m "chore(changelog): regenerate for ${{ github.ref_name }} [skip ci]"
git push origin master
fi
# ---- (4) Publish GitHub Release ----
- name: Create GitHub Release
uses: softprops/action-gh-release@v2
with:
CHANGELOG.md
+8703 -444
View File
File diff suppressed because it is too large Load Diff
cliff.toml
+42 -20
View File
@@ -8,15 +8,41 @@
# → release published.
[changelog]
# Header rendered once at top of every release body.
# Header rendered once at top of CHANGELOG.md (preserved across full regens).
# Use `--strip header` on `--latest` for GitHub Release bodies so they don't
# duplicate this intro on every release page.
header = """
# Changelog
Auto-generated from commit messages by [git-cliff](https://git-cliff.org/).
Update flow: write rich commit message bodies → tag → CI regenerates this file
and the GitHub Release notes from the same source. Don't hand-edit below the
header — your changes will be overwritten on the next tag.
**Versioning:** SemVer in `0.x` — treat any minor bump as potentially breaking
until `1.0`. Past CalVer tags (`v2026.05.09`, `v2026.05.10`) are preserved for
history; SemVer takes over from `v0.3.0` onward.
| CalVer tag | SemVer equivalent | Date |
|---|---|---|
| `v2026.05.09` | (≈ v0.1.0) | 2026-05-09 — first tagged release |
| `v2026.05.10` | (≈ v0.2.0) | 2026-05-10 — stack reorg + Gemma 4 INT8 PTH unblock |
---
"""
# Body template — rendered per release (we use --latest so only one).
# Tera templating syntax. Each commit shows as a bullet with PR link if present.
# Body template — rendered per release. For `--latest` (GitHub Release) only
# the most recent block renders; for full regen of CHANGELOG.md, every tagged
# block renders in reverse-chronological order.
#
# Commit message body (everything after subject + blank line) renders below
# the subject bullet so rich narrative (tables, validation data, before/after
# numbers) ends up in both CHANGELOG.md and the GitHub Release page from the
# same source. Tera templating; see https://keats.github.io/tera/docs/.
body = """
{% if version %}\
## What's in {{ version }}
## {{ version }}{% if timestamp %} — {{ timestamp | date(format="%Y-%m-%d") }}{% endif %}
{% else %}\
## Unreleased
@@ -26,25 +52,21 @@ body = """
### {{ group }}
{% for commit in commits %}\
- {{ commit.message | split(pat="\\n") | first | trim }}{% if commit.github.pr_number %} ([#{{ commit.github.pr_number }}](https://github.com/noonghunna/club-3090/pull/{{ commit.github.pr_number }}) by @{{ commit.github.username }}){% else %} ([{{ commit.id | truncate(length=7, end="") }}](https://github.com/noonghunna/club-3090/commit/{{ commit.id }})){% endif %}
{% endfor %}
{% endfor %}
- **{{ commit.message | split(pat="\\n") | first | trim }}**{% if commit.github.pr_number %} ([#{{ commit.github.pr_number }}](https://github.com/noonghunna/club-3090/pull/{{ commit.github.pr_number }}) by @{{ commit.github.username }}){% else %} ([{{ commit.id | truncate(length=7, end="") }}](https://github.com/noonghunna/club-3090/commit/{{ commit.id }})){% endif %}
{% set body_lines = commit.message | split(pat="\\n") %}\
{% if body_lines | length > 1 %}\
{% set body = body_lines | slice(start=1) | join(sep="\\n") | trim %}\
{% if body %}
---
{{ body | replace(from="\\n", to="\\n ") }}
## Pinning to this release
**Versioning:** SemVer in `0.x` — treat any minor bump as potentially breaking until `1.0`. Past CalVer tags (`v2026.05.09`, `v2026.05.10`) are preserved for history; SemVer takes over from `v0.3.0` onward.
```bash
git checkout {{ version }}
```
When posting cross-rig benchmark numbers ([disc #86](https://github.com/noonghunna/club-3090/discussions/86)), please include this version tag (or commit SHA) so others can reproduce against the same script revision.
{% if previous.version %}\
**Full diff:** [{{ previous.version }}...{{ version }}](https://github.com/noonghunna/club-3090/compare/{{ previous.version }}...{{ version }})
{% endif %}\
{% endif %}\
{% endfor %}
{% endfor %}
{% if version %}[Pin: `git checkout {{ version }}`]{% if previous.version %} · [Full diff](https://github.com/noonghunna/club-3090/compare/{{ previous.version }}...{{ version }}){% endif %}
{% endif %}
"""
footer = ""