sarman/tftsr-devops_investigation
1
0
Fork 0
Code Issues 1 Pull Requests Actions 34 Packages Projects 3 Releases 9 Wiki Activity
v0.2.55
tftsr-devops_investigation/ticket-git-cliff-changelog.md
Shaun Arman 6d2b69ffb0 feat(ci): add automated changelog generation via git-cliff 
- 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
2026-04-12 21:56:16 -05:00

3.8 KiB
Raw Permalink Blame History

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