shouenlee/release_notes

Release Notes

Generate changelogs, bump semantic versions, and publish GitHub releases from conventional commits.

When to Use

• You want to generate a changelog from commits since the last release
• You need to determine and apply the next semantic version bump
• You want to create a GitHub release with auto-generated notes

Prerequisites

• Git repository with conventional commit messages (e.g., feat:, fix:, docs:)
• At least one existing git tag for changelog generation (e.g., v1.0.0)
• gh CLI installed and authenticated for publishing releases (gh auth status)

Workflow

/release notes — Generate changelog

1. Find the most recent git tag:

   git describe --tags --abbrev=0
   

   Or use a user-specified tag as the starting point.

2. Get all commits since that tag:

   git log <tag>..HEAD --pretty=format:"%h %s" --no-merges
   

3. Parse conventional commit prefixes from each commit message (feat, fix, docs, chore, perf, refactor, test, ci, style).

4. Group commits by type with human-readable headers:

   • Features — feat commits
   • Bug Fixes — fix commits
   • Documentation — docs commits
   • Performance — perf commits
   • Breaking Changes — commits containing BREAKING CHANGE in the body or ! after the type
   • Other — refactor, test, chore, ci, style commits

5. Generate markdown changelog with version header and date:

   ## v1.2.0 (2026-03-02)
   
   ### Features
   - abc1234 Add user authentication flow
   
   ### Bug Fixes
   - def5678 Fix null pointer in config parser
   

6. Include links to commits if a GitHub remote is available:

   - [`abc1234`](https://github.com/owner/repo/commit/abc1234) Add user authentication flow
   

7. Output the changelog to stdout, or offer to prepend it to CHANGELOG.md.

/release bump — Semantic version bump

1. Analyze commits since the last tag to determine the bump type:

   BREAKING CHANGE or ! → major
   feat                 → minor
   fix, perf, refactor  → patch
   

2. Calculate the new version from the current tag:

   # Example: v1.2.3 with a feat commit → v1.3.0
   git describe --tags --abbrev=0  # returns v1.2.3
   

3. Update the version in the project manifest if present:

   # pyproject.toml: [project] version = "1.3.0"
   # package.json:   "version": "1.3.0"
   

4. Show the planned change and ask for confirmation:

   Version bump: v1.2.3 → v1.3.0 (minor — new features detected)
   Updated: pyproject.toml
   

5. Create a new git tag:

   git tag v1.3.0
   

/release publish — Create GitHub release

1. Determine the latest tag, or accept a user-specified tag:

   git describe --tags --abbrev=0
   

2. Generate release notes using the same logic as /release notes.

3. Create the GitHub release:

   gh release create <tag> --title "<tag>" --notes "<changelog>"
   

4. Offer additional options:

   • --draft — create as a draft release
   • --prerelease — mark as a pre-release
   • Attach binary assets if the user provides file paths

5. Confirm with the user before publishing the release.

Troubleshooting

| Problem | Cause | Solution | |---|---|---| | fatal: No names found | No git tags exist in the repository | Create an initial tag with git tag v0.1.0 | | Commits not grouped correctly | Commit messages don't follow conventional format | Use type: description format (e.g., feat: add login) | | gh: not logged in | gh CLI is not authenticated | Run gh auth login | | Version not updated in manifest | No pyproject.toml or package.json found | Manually specify the file or create the manifest | | Tag already exists | The computed version tag already exists | Use a different version or delete the existing tag |