| name | release-workflow |
| description | Release conventions and changelog configuration for lunar-claude, covering version bumping, changelog generation via git-cliff, and release tagging.
|
| when_to_use | Use when preparing a release, bumping the version, updating the changelog, creating a release tag, determining what version something should be, or understanding the changelog/release process.
|
Release Workflow
Project-specific release conventions for lunar-claude. For the interactive
release workflow, use the /generate-changelog command from the git-workflow
plugin.
Current Release State
- Latest tag: !
git describe --tags --abbrev=0 2>/dev/null || echo "No tags yet"
- Marketplace version: !
jq -r '.metadata.version' .claude-plugin/marketplace.json
- Unreleased commits: !
git log --oneline $(git describe --tags --abbrev=0 2>/dev/null)..HEAD 2>/dev/null | wc -l | tr -d ' '
Version Scheme
- Semantic versioning:
MAJOR.MINOR.PATCH
- Tag format:
v0.x.y (prefixed with v)
- Marketplace and plugin manifests track versions independently
Version Bump Decision
| Commit types present | Bump level |
|---|
BREAKING CHANGE: in footer or ! after type | Major |
feat: (new features) | Minor |
fix:, docs:, refactor:, perf:, test:, chore: only | Patch |
Commit → Changelog Group Mapping
git-cliff (cliff.toml) maps conventional commits to changelog groups:
| Commit prefix | Changelog group |
|---|
feat | 🚀 Features |
fix | 🐛 Bug Fixes |
refactor | 🚜 Refactor |
doc | 📚 Documentation |
perf | ⚡ Performance |
style | 🎨 Styling |
test | 🧪 Testing |
chore, ci | ⚙️ Miscellaneous Tasks |
| body contains "security" | 🛡️ Security |
revert | ◀️ Revert |
Auto-Skipped Commits
These are filtered out of the changelog automatically:
chore(release): prepare for — release prep commitschore(deps*) — dependency updates (Renovate/Dependabot)chore(pr) / chore(pull) — PR merge housekeeping
Files to Update on Release
- CHANGELOG.md — Generated by
git-cliff --tag vX.Y.Z -o CHANGELOG.md
.claude-plugin/marketplace.json — Update metadata.version- Plugin manifests — Update
version in each changed plugin's
plugins/<cat>/<name>/.claude-plugin/plugin.json (only if that plugin changed)
Release Commit & Tag
$ git add CHANGELOG.md .claude-plugin/marketplace.json
$ git commit -m "docs: update changelog for vX.Y.Z"
$ git tag -a vX.Y.Z -m "Release vX.Y.Z"
$ git push && git push --tags
GitHub Actions (release.yml) automatically creates the GitHub release from
the tag, generating release notes via git-cliff.
Gotchas
- Push tags separately:
git push does not push tags — always follow with
git push --tags
- Marketplace version: Easy to forget updating
.claude-plugin/marketplace.json
alongside CHANGELOG.md
- Plugin versions are independent: Only bump a plugin's version if that
plugin had changes — not every release bumps every plugin
- Pre-release tags: Tags containing
rc, beta, or alpha are marked as
pre-release in GitHub automatically
- Dependency commits vanish: Renovate/Dependabot commits are auto-skipped
in the changelog — this is intentional, not a bug
