d5e180740e
Replace every remaining reference to the old Gitea infrastructure with the new GitHub-hosted equivalents across all documentation, wiki pages, test files, and historical ticket summaries. - README.md: CI badge, clone URL, releases link, CI/CD section, project structure - docs/wiki/CICD-Pipeline.md: full rewrite for GitHub Actions + ghcr.io - docs/wiki/Home.md: CI badge, releases link, phase status, tech stack - docs/wiki/Troubleshooting.md: rewrite CI troubleshooting for GitHub Actions - docs/architecture/README.md: update CI/CD pipeline diagram - AGENTS.md: CI/CD section, environment references - PLAN.md: directory structure, pipeline table - SECURITY_AUDIT.md: mark C3 and L4 findings as resolved - ticket-git-cliff-changelog.md: workflow path updated - tickets/ci-runner-speed-optimization.md: image registry updated - 2026-hackathon_AgenticFeature.md: workflow path updated - tests: workflow path assertions updated in all three test files
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
|
|
- `.github/workflows/release.yml` — `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 `release.yml` runs after `autotag` (parallel with build jobs)
|
|
- [ ] Each GitHub Release body shows grouped conventional-commit entries instead of
|
|
static `"Release vX.Y.Z"`
|
|
- [ ] `CHANGELOG.md` committed to `main` 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
|
|
|
|
### `.github/workflows/release.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`)
|
|
- Updates the GitHub Release body via `gh release edit` with JSON-safe escaping (`jq -Rs .`)
|
|
- Commits `CHANGELOG.md` to `main` 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
|