From cc1a164bc15c73ea19d8ad069a16a1f706021746 Mon Sep 17 00:00:00 2001
From: rob thijssen <grenade@rob.tn>
Date: Thu, 16 Apr 2026 15:22:20 +0300
Subject: [PATCH] docs: add CLAUDE.md with release and tagging workflow

Documents the v<major> + v<major.minor.patch> dual-tag pattern so
any future Claude session (or human) can make a release without
re-deriving the conventions. Includes a local dry-run recipe and
lists known consumers.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md | 119 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 119 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..f4e7851
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,119 @@
+# 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. Both the immutable semver tag and the moving major
+   tag get pushed in the same command:
+
+   ```sh
+   git tag v1.0.4
+   git tag -f 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`):
+
+   ```sh
+   git tag v2.0.0
+   git tag 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:
+
+```sh
+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.