rpm-changelog/CLAUDE.md

CLAUDE.md — rpm-changelog

Project overview

Composite Gitea Action that generates rpm %changelog entries from git history and prepends them to a target spec file. Consumed by release CI across helexa/* and grenade/* projects that ship rpms.

See README.md for usage. This file covers the release workflow and conventions specific to publishing the action itself.

Repository layout

rpm-changelog/
├── action.yml              # composite action manifest
├── scripts/
│   └── generate-rpm-changelog.sh
├── README.md               # user-facing docs
└── CLAUDE.md               # ← you are here

Release workflow

Consumers pin to a major-version tag (e.g. @v1) which tracks the latest release in that major line. Every release gets both a moving major-version tag and an immutable semver tag.

On a normal change (bug fix, internal refactor, non-breaking feature)

1. Commit changes to main with a conventional-commit message.

2. Determine the next version by bumping the patch or minor from the latest semver tag (e.g. v1.0.3 → v1.0.4 for a fix, v1.1.0 for a non-breaking feature).

3. Tag and push. This repo has tag.gpgsign=true globally, so tags must be annotated with a message (-m) and a GPG key must be available. Both the immutable semver tag and the moving major tag get pushed in the same release:

   git tag -m "v1.0.4" v1.0.4
   git tag -f -m "v1 - track latest v1.x.y" v1
   git push origin main
   git push origin v1.0.4
   git push origin v1 --force
   

   The -f / --force on the major tag is intentional — it's a moving ref by design. Consumers pinned to @v1 pick up the new release on their next workflow run.

On a breaking change

1. Commit to main.

2. Cut a new major tag (v2.0.0) and a new major-line tag (v2):

   git tag -m "v2.0.0" v2.0.0
   git tag -m "v2 - track latest v2.x.y" v2
   git push origin main v2.0.0 v2
   

3. Do not move v1 — projects still pinned to @v1 keep working against the last v1.x release. Update v1 only for bugfix backports.

Dry run before pushing

There's no test harness in this repo (composite actions with shell scripts are hard to unit-test in isolation). Before publishing a release, run the script locally against a sample spec to sanity-check:

cd /tmp && mkdir -p fake && cd fake
git init && git commit --allow-empty -m "init"
git tag v0.0.1
git commit --allow-empty -m "feat: add thing"
git commit --allow-empty -m "chore: bump version to 0.0.2"

cp /path/to/some.spec .
~/git/actions/rpm-changelog/scripts/generate-rpm-changelog.sh some.spec 0.0.2
cat some.spec | head -20

Verify the new entry appears above any existing %changelog block with a correct weekday, the right commits listed, and bot-authored commits filtered out.

Conventions

• Shell: bash only. No zsh-isms, no node, no python — runners must work with nothing beyond a Fedora base install.
• Dependencies: git, grep -E, awk, date, mktemp. All present by default on Fedora.
• Style: set -euo pipefail at the top of every script. Quote all variable expansions. Use printf over echo when content could start with -.
• Commit messages: conventional commits (feat:, fix:, docs:, chore:). This action's own %changelog isn't generated (it's not an rpm), but commit hygiene still matters for anyone reading git log to diagnose a regression.

Consuming projects

As of this writing:

• helexa/cortex — uses @v1 via Gitea's full-URL syntax: uses: https://git.lair.cafe/actions/rpm-changelog@v1.

When adding a new consumer, update this list so future sessions know what breaks if a release is botched.

Not this action's job

• Generating human-readable CHANGELOG.md files — that's requarks/changelog-action territory. This action only cares about the rpm spec's %changelog section.
• Creating GitHub/Gitea releases — that belongs in the consumer's release job.
• Running rpmbuild or signing — handled by rpmbuild -bs in the consumer, signing is done by COPR.