Automatically compare code changes when tagging and generate standardized Release Notes.
Overview
Compare the git history from the previous tag to the current HEAD, classify by conventional commit (feat/fix/docs/refactor/chore), automatically detect breaking changes, and generate standardized Release Notes. Optionally create a git tag and GitHub Release.
When to Use
- User wants to create a tag or release
- User wants to summarize version changes
- User mentions changelog, release notes, or version documentation
- User inputs
/release-notes - User wants to generate a CHANGELOG.md from commit history
- User wants to prepare a release with categorized changes
- User wants to auto-detect breaking changes before release
- User wants to create an annotated git tag with release notes
When NOT to Use:
- User only wants to view git log
- User wants to modify existing release notes
- User wants to generate changelogs for multiple repositories (different tooling)
- User wants to automate release notes in CI/CD (consider semantic-release or release-please)
Core Pattern
Step 1: Detect version number
Get the latest tag (git describe --tags --abbrev=0), user-specified version number, or suggest based on change type: breaking changes → major, new features → minor, only bugfixes → patch.
Step 2: Compare changes
PREV_TAG=$(git describe --tags --abbrev=0)
git log ${PREV_TAG}..HEAD --oneline
git diff ${PREV_TAG}..HEAD --stat
Step 3: Classify changes
| Category | Prefix | Description |
|---|---|---|
| 🚀 Features | feat: |
New features |
| 🐛 Bug Fixes | fix: |
Fixes |
| 📝 Documentation | docs: |
Documentation |
| ♻️ Refactor | refactor: |
Refactoring |
| 🔧 Chores | chore: |
Build/tooling/config |
| ⚡ Performance | perf: |
Performance optimization |
| 🧪 Tests | test: |
Tests |
| 🔒 Security | security: |
Security fixes |
| 💥 Breaking Changes | BREAKING CHANGE or ! suffix |
Breaking changes |
Breaking Changes detection rules:
- commit message contains
BREAKING CHANGE:orBREAKING CHANGES: - commit type followed by
!(e.g.feat!:、fix!:） - commit body contains a breaking change description
Read the conventional commit prefix in the commit message; for those without a prefix, infer based on file changes.
Step 4: Generate Notes
Generate using the templates/release-notes.md template, including version number, date, categorized change list, and diff link.
Step 5: Create Tag/Release (optional)
Ask the user whether to create an annotated tag and GitHub Release. Use the notes generated by this skill as the release body:
# 创建 annotated tag
git tag -a "$TAG" -m "$TAG"
# 创建 GitHub Release，使用生成的 release notes
gh release create "$TAG" --title "$TAG" --notes-file release-notes.md
Quick Reference
/release-notes # 交互式，自动建议版本号
/release-notes v1.1.0 # 指定版本号
/release-notes --dry-run # 只生成不创建 tag
| Parameter | Description | Default value |
|---|---|---|
version |
Version number | Auto-suggested |
--dry-run |
Only generate, do not create | false |
Common Mistakes
| Error | Correct approach | Reason |
|---|---|---|
| Only look at commit count | Analyze actual code changes | Commit count does not represent change scale |
| Ignore breaking changes | Highlight with 💥 | Users need to know about incompatible changes |
| Do not classify, list everything together | Group by feat/fix/docs | Poor readability |
| Notes too long | Condense to key changes + diff link | Users do not need to see every detail |
| Directly ignore commits without a prefix | Infer type based on file changes | Not all teams strictly use conventional commits |
| Version number skips semver rules | Follow major.minor.patch semantics | Arbitrary numbering causes dependency management chaos |
| Do not check the API impact of breaking changes | Annotate affected interfaces and migration methods | Users only discover breaking changes after upgrading |
| Release Notes do not include a diff link | Add ${PREV_TAG}...${TAG} comparison link |
Convenient for users to view specific code changes |