6d2b69ffb0
- Add cliff.toml with Tera template: feat/fix/perf/docs/refactor included; ci/chore/build/test/style excluded - Bootstrap CHANGELOG.md from all existing semver tags (v0.1.0–v0.2.49) - Add changelog job to auto-tag.yml: runs after autotag in parallel with build jobs; installs git-cliff v2.7.0 musl binary, generates CHANGELOG.md, PATCHes Gitea release body with per-release notes, commits CHANGELOG.md to master with [skip ci] to prevent re-trigger, uploads as release asset - Add set -eu to all changelog job steps - Null-check RELEASE_ID before API calls; create release if missing (race-condition fix: changelog finishes before build jobs create release) - Add Changelog Generation section to docs/wiki/CICD-Pipeline.md
75 lines
3.8 KiB
Markdown
75 lines
3.8 KiB
Markdown
# feat: Automated Changelog via git-cliff
|
|
|
|
## Description
|
|
|
|
Introduces automated changelog generation using **git-cliff**, a tool that parses
|
|
conventional commits and produces formatted Markdown changelogs.
|
|
|
|
Previously, every Gitea release body contained only the static text `"Release vX.Y.Z"`.
|
|
With this change, releases display a categorised, human-readable list of all commits
|
|
since the previous version.
|
|
|
|
**Root cause / motivation:** No changelog tooling existed. The project follows
|
|
Conventional Commits throughout but the information was never surfaced to end-users.
|
|
|
|
**Files changed:**
|
|
- `cliff.toml` (new) — git-cliff configuration; defines commit parsers, ignored tags,
|
|
output template, and which commit types appear in the changelog
|
|
- `CHANGELOG.md` (new) — bootstrapped from all existing tags; maintained by CI going forward
|
|
- `.gitea/workflows/auto-tag.yml` — new `changelog` job that runs after `autotag`
|
|
- `docs/wiki/CICD-Pipeline.md` — "Changelog Generation" section added
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] `cliff.toml` present at repo root with working Tera template
|
|
- [ ] `CHANGELOG.md` present at repo root, bootstrapped from all existing semver tags
|
|
- [ ] `changelog` job in `auto-tag.yml` runs after `autotag` (parallel with build jobs)
|
|
- [ ] Each Gitea release body shows grouped conventional-commit entries instead of
|
|
static `"Release vX.Y.Z"`
|
|
- [ ] `CHANGELOG.md` committed to master on every release with `[skip ci]` suffix
|
|
(no infinite re-trigger loop)
|
|
- [ ] `CHANGELOG.md` uploaded as a downloadable release asset
|
|
- [ ] CI/chore/build/test/style commits excluded from changelog output
|
|
- [ ] `docs/wiki/CICD-Pipeline.md` documents the changelog generation process
|
|
|
|
## Work Implemented
|
|
|
|
### `cliff.toml`
|
|
- Tera template with proper whitespace control (`-%}` / `{%- `) for clean output
|
|
- Included commit types: `feat`, `fix`, `perf`, `docs`, `refactor`
|
|
- Excluded commit types: `ci`, `chore`, `build`, `test`, `style`
|
|
- `ignore_tags = "rc|alpha|beta"` — pre-release tags excluded from version boundaries
|
|
- `filter_unconventional = true` — non-conventional commits dropped silently
|
|
- `sort_commits = "oldest"` — chronological order within each version
|
|
|
|
### `CHANGELOG.md`
|
|
- Bootstrapped locally using git-cliff v2.7.0 (aarch64 musl binary)
|
|
- Covers all tagged versions from `v0.1.0` through `v0.2.49` plus `[Unreleased]`
|
|
- 267 lines covering the full project history
|
|
|
|
### `.gitea/workflows/auto-tag.yml` — `changelog` job
|
|
- `needs: autotag` — waits for the new tag to exist before running
|
|
- Full history clone: `git fetch --tags --depth=2147483647` so git-cliff can resolve
|
|
all version boundaries
|
|
- git-cliff v2.7.0 downloaded as a static x86_64 musl binary (~5 MB); no custom
|
|
image required
|
|
- Generates full `CHANGELOG.md` and per-release notes (`--latest --strip all`)
|
|
- PATCHes the Gitea release body via API with JSON-safe escaping (`jq -Rs .`)
|
|
- Commits `CHANGELOG.md` to master with `[skip ci]` to prevent workflow re-trigger
|
|
- Deletes any existing `CHANGELOG.md` asset before re-uploading (rerun-safe)
|
|
- Runs in parallel with all build jobs — no added wall-clock latency
|
|
|
|
### `docs/wiki/CICD-Pipeline.md`
|
|
- Added "Changelog Generation" section before "Known Issues & Fixes"
|
|
- Describes the five-step process, cliff.toml settings, and loop prevention mechanism
|
|
|
|
## Testing Needed
|
|
|
|
- [ ] Merge this PR to master; verify `changelog` CI job succeeds in Gitea Actions
|
|
- [ ] Check Gitea release body for the new version tag — should show grouped commit list
|
|
- [ ] Verify `CHANGELOG.md` was committed to master (check git log after CI runs)
|
|
- [ ] Verify `CHANGELOG.md` appears as a downloadable asset on the release page
|
|
- [ ] Push a subsequent commit to master; confirm the `[skip ci]` CHANGELOG commit does
|
|
NOT trigger a second run of `auto-tag.yml`
|
|
- [ ] Confirm CI/chore commits are absent from the release body
|