Release Notes Generator

Generates structured release notes from git history, conventional commits, and linked issues with changelog formatting and distribution-ready output.

When to Use This Command

Run this command when you need to:

• Generate release notes from git commits between two tags or refs with automatic categorization by commit type (feat, fix, chore, docs)
• Create changelog entries formatted for GitHub Releases, CHANGELOG.md, Slack announcements, or email distribution
• Produce user-facing release summaries that translate technical commit messages into product-oriented feature descriptions

Consider alternatives when:

• You need continuous changelog maintenance rather than point-in-time release generation
• Your project does not follow conventional commits or any structured commit message format

Quick Start

Configuration

Copy
name: release-notes-generator
type: command
category: git-workflow

Example Invocation

Copy
claude command:run release-notes-generator --from v1.2.0 --to v1.3.0

Example Output

Release Notes: v1.3.0
=====================
Date: 2026-03-15
Commits: 47 | Contributors: 8

## New Features
- **User dashboard redesign** — Complete visual overhaul of the
  main dashboard with real-time data widgets (#234)
- **Export to PDF** — Users can now export reports as formatted
  PDF documents with custom headers (#241)

## Bug Fixes
- Fixed pagination reset when applying filters (#238)
- Resolved timezone display issue in activity logs (#240)
- Fixed memory leak in WebSocket connection handler (#245)

## Improvements
- Reduced API response time by 40% through query optimization
- Updated dependencies to latest security patches
- Improved error messages for form validation

## Breaking Changes
- Removed deprecated /api/v1/users endpoint (use /api/v2/users)

Full changelog: https://github.com/org/repo/compare/v1.2.0...v1.3.0

Core Concepts

Release Notes Overview

Aspect	Details
Commit Parsing	Analyzes conventional commit prefixes (feat:, fix:, chore:, docs:, refactor:, perf:) to categorize changes automatically
Issue Linking	Extracts issue references (#123, GH-456) from commit messages and fetches issue titles for human-readable descriptions
Breaking Changes	Detects BREAKING CHANGE footers and ! markers in commit messages, surfacing them in a dedicated section
Multi-Format Output	Generates notes in markdown, GitHub Release format, Slack Block Kit, plain text, or custom templates

Release Notes Workflow

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Parse Git   │────▶│  Categorize  │────▶│  Fetch Issue │
│  Log Range   │     │  By Type     │     │  Metadata    │
└──────────────┘     └──────────────┘     └──────────────┘
       │                    │                     │
       ▼                    ▼                     ▼
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Detect      │────▶│  Format      │────▶│  Distribute  │
│  Breaking    │     │  Output      │     │  (GH/Slack)  │
└──────────────┘     └──────────────┘     └──────────────┘

Configuration

Parameter	Type	Default	Description
from	string	latest-tag	Starting git ref (tag, commit, or branch) for the release range
to	string	HEAD	Ending git ref for the release range
format	enum	markdown	Output format: markdown, github-release, slack, plaintext, or custom
include_contributors	boolean	true	List contributors with commit counts in the release notes
publish	boolean	false	Automatically create a GitHub Release with the generated notes

Best Practices

1. Use Conventional Commits Consistently The generator produces the best results when all commits follow the conventional commits specification. Enforce this with a commit-msg hook or CI check so every commit is parseable into a release notes category.

2. Write User-Facing Commit Descriptions Commit messages like "fix: resolve issue" produce poor release notes. Write messages like "fix: pagination resets when applying date filters" that describe the user-visible behavior change. The generator passes these descriptions directly to the release notes.

3. Tag Releases Before Generating Notes Create the git tag first so the generator has a clean ref range. Generating notes against HEAD on an active branch may include work-in-progress commits that should not appear in the release.

4. Review Generated Notes Before Publishing The generator produces a draft that may need editorial polish. Technical commit messages may need rewriting for user-facing audiences. Review and edit the draft before publishing to GitHub Releases or distributing to stakeholders.

5. Include Migration Instructions for Breaking Changes When the generator detects breaking changes, add migration instructions manually to the generated notes. Users need to know not just what changed but how to update their code or configuration to accommodate the change.

Common Issues

1. Commits without conventional prefixes are miscategorized Non-conventional commits (e.g., "Updated the login page") default to an "Other" category. Configure a fallback_category to place these under a specific heading, or enforce conventional commits project-wide to eliminate unstructured messages.

2. Merge commits create duplicate entries When using merge commits (not squash), both the individual commits and the merge commit appear in the log. Set exclude_merges to true to filter merge commits and only show the original feature commits.

3. Issue references not resolving to titles The generator fetches issue titles via the GitHub API, which requires authentication for private repositories. Set the GITHUB_TOKEN environment variable or configure the gh CLI with appropriate credentials for your organization.