# Release Workflow

> 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.

- Skill: `majiayu000/release-workflow-3` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/release-workflow-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/release-workflow-3/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/release-workflow-3

---


# 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