Changelog Generator

Generate CHANGELOG.md entries from git history following Keep a Changelog format.

Workflow

1. Detect range → 2. Collect commits → 3. Enrich with PRs → 4. Classify → 5. Format → 6. Update file

1. Detect Range

Determine what commits to include:

# Find latest version tag
git tag --sort=-v:refname | head -20

Range selection:

• If CHANGELOG.md has ## [Unreleased] — collect commits since last version tag
• If user specifies a range — use that (v1.0.0..HEAD, --since="2 weeks ago")
• If no tags exist — collect all commits on the default branch
• If user says "release X.Y.Z" — collect unreleased commits, stamp with version and date

2. Collect Commits

# Commits since last tag (or all if no tags)
git log v1.0.0..HEAD --format="%H|%s|%an|%aI" --no-merges

For merge-based workflows, also collect merge commits to find PR numbers:

git log v1.0.0..HEAD --format="%H|%s" --merges

3. Enrich with PR/Issue Data

If the repo is on GitHub, enrich commits with PR metadata:

# Get PRs merged since last tag
gh pr list --state merged --base main --json number,title,labels,mergedAt --limit 100

Or for a specific date range:

gh pr list --state merged --search "merged:>2026-01-01" --json number,title,labels,body --limit 100

Match commits to PRs via:

• PR number in commit message (e.g., (#123))
• Merge commit references
• gh pr list merged date within range

4. Classify Changes

Map commits/PRs to Keep a Changelog categories using Conventional Commits prefixes and PR labels:

Category	Conventional Commits	PR Labels
Added	feat:, feat(scope):	feature, enhancement
Changed	refactor:, perf:, build:	refactor, performance
Deprecated	deprecate:	deprecation
Removed	commit message contains "remove", "delete"	removal
Fixed	fix:, fix(scope):	bug, bugfix
Security	security:	security, vulnerability

Classification rules:

• Conventional Commit prefix takes priority over PR labels
• If no prefix and no label, classify as Changed
• Skip commits matching: chore:, ci:, docs: (unless docs: adds user-facing docs)
• Skip commits matching: Merge branch, Merge pull request (metadata, not changes)
• Group by scope when present: feat(auth): → group under auth

5. Format Entries

Follow Keep a Changelog format strictly:

## [X.Y.Z] - YYYY-MM-DD

### Added
- **scope**: Description of feature ([#123](link))

### Fixed
- Description of fix ([#456](link))

Formatting rules:

• One bullet per logical change (merge related commits into single entry)
• Start each entry with bold scope if scope is present in commit
• Link PR numbers: ([#123](https://github.com/OWNER/REPO/pull/123))
• Link issue numbers: ([#456](https://github.com/OWNER/REPO/issues/456))
• Use imperative mood for descriptions (Add, Fix, Remove — not Added, Fixed, Removed)
• Keep entries concise — one line per change, details belong in PR descriptions
• Order categories: Added → Changed → Deprecated → Removed → Fixed → Security

6. Update File

If CHANGELOG.md exists:

• Insert new version section below ## [Unreleased] header
• If stamping a release, replace ## [Unreleased] content with versioned section, add empty ## [Unreleased] above
• Update comparison links at bottom of file

If CHANGELOG.md does not exist:

• Create with full Keep a Changelog header
• Include ## [Unreleased] section
• Add comparison links

Comparison links (bottom of file):

[Unreleased]: https://github.com/OWNER/REPO/compare/vX.Y.Z...HEAD
[X.Y.Z]: https://github.com/OWNER/REPO/compare/vX.Y.Z-1...vX.Y.Z

Usage Patterns

Update Unreleased Section

Default behavior — collect all changes since last tag:

"Update the changelog"

Stamp a Release

Move unreleased entries to a versioned section:

"Release v2.1.0"

Result: ## [Unreleased] becomes empty, ## [2.1.0] - 2026-02-23 added with entries.

Changelog for Range

Generate entries for a specific commit range:

"Changelog for v1.0.0..v2.0.0"

First Changelog

Create CHANGELOG.md from scratch for a repo without one:

"Create a changelog for this project"

Edge Cases

• Squash merges: Commit message often contains full PR description — extract the title line only
• Monorepo: If user specifies a path, filter commits with -- path/to/package
• No Conventional Commits: Fall back to PR titles and labels for classification; if neither available, list all as Changed
• Amended/rebased history: Use --first-parent to follow mainline only
• Multiple tags on same commit: Use the highest semver tag