playbooks

home / skills / basher83 / lunar-claude / release-workflow

release-workflow skill

/.claude/skills/release-workflow

This skill helps you manage release workflow by guiding version bumps, changelog updates, and tag creation aligned with semantic versioning.

npx playbooks add skill basher83/lunar-claude --skill release-workflow

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
3.2 KB
---
name: release-workflow
description: >
  Release conventions and changelog configuration for lunar-claude.
  Use when the user asks to "prepare a release", "bump the version",
  "update the changelog", "create a release tag", "what version should
  this be", or needs to understand 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 commits
- `chore(deps*)` — dependency updates (Renovate/Dependabot)
- `chore(pr)` / `chore(pull)` — PR merge housekeeping

## Files to Update on Release

1. **CHANGELOG.md** — Generated by `git-cliff --tag vX.Y.Z -o CHANGELOG.md`
2. **`.claude-plugin/marketplace.json`** — Update `metadata.version`
3. **Plugin manifests** — Update `version` in each changed plugin's
   `plugins/<cat>/<name>/.claude-plugin/plugin.json` (only if that plugin changed)

## Release Commit & Tag

```bash
$ 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

Overview

This skill codifies the release conventions and changelog workflow for the lunar-claude repo. It guides version decisions, changelog generation, and which files to update for a release. Use it to prepare a release, bump versions, or create tags consistently.

How this skill works

It inspects git history and conventional commit types to determine whether a major, minor, or patch bump is required. It uses git-cliff to map commits into changelog groups and generate CHANGELOG.md, and it updates the marketplace and plugin manifest versions when appropriate. The workflow culminates in committing the changelog and metadata, tagging the release (vMAJOR.MINOR.PATCH), and pushing commits and tags so CI creates the GitHub release.

When to use it

  • When you need to prepare a new release or generate release notes
  • When asked "what version should this be" based on recent commits
  • When you need to bump the marketplace or plugin version(s)
  • Before tagging a release so CHANGELOG.md and manifests are up to date
  • When creating a GitHub release via CI or manually tagging

Best practices

  • Follow conventional commit messages so the bump decision is accurate (feat, fix, BREAKING CHANGE).
  • Run git-cliff to generate CHANGELOG.md with the appropriate tag: git-cliff --tag vX.Y.Z -o CHANGELOG.md.
  • Only bump plugin manifest versions for plugins that actually changed; marketplace version is independent but must be updated.
  • Always git add/commit the changelog and marketplace manifest, then tag with git tag -a vX.Y.Z -m "Release vX.Y.Z" and run git push && git push --tags.
  • Remember git push does not push tags by default — push tags explicitly to trigger the release action.

Example use cases

  • Prepare a patch release after several fix: commits and a few docs: updates.
  • Decide between minor or patch bump when new feat: commits are mixed with fixes.
  • Generate CHANGELOG.md for an upcoming release using git-cliff and include only relevant commit groups.
  • Update .claude-plugin/marketplace.json metadata.version and tag the release to trigger GitHub Actions.
  • Bump a single plugin's plugins/<cat>/<name>/.claude-plugin/plugin.json version when that plugin changed.

FAQ

How is the version bump level determined?

Major if a BREAKING CHANGE footer or ! after type is present; minor for feat:; patch for fix:, docs:, refactor:, perf:, test:, chore: only.

Do I need to bump every plugin manifest on each release?

No. Only update a plugin's version if that specific plugin had code or manifest changes; marketplace version is tracked separately.