Changelog Generator

Tier: POWERFUL Category: Engineering / Release Management Maintainer: Claude Skills Team

Overview

Generate consistent, auditable changelogs and release notes from Conventional Commits. Parses commit messages, detects semantic version bumps (major/minor/patch), renders Keep a Changelog sections, supports monorepo scoped changelogs, integrates with CI for automated release notes, and enforces commit format with linting. Separates commit parsing, bump logic, and rendering so teams can automate releases without losing editorial control.

Keywords

changelog, release notes, conventional commits, semantic versioning, semver, Keep a Changelog, commit linting, release automation, monorepo changelog

Core Capabilities

1. Commit Parsing

• Parse Conventional Commit messages into structured data

• Extract type, scope, description, body, and footer

• Detect breaking changes from ! suffix and BREAKING CHANGE: footer

• Handle multi-line commit bodies and co-author trailers

2. Semantic Version Detection

• Map commit types to version bump levels

• Breaking changes trigger major bumps

• feat triggers minor bumps

• All other types trigger patch bumps

• Support for pre-release versions (alpha, beta, rc)

3. Changelog Rendering

• Keep a Changelog format with semantic sections

• GitHub release notes format

• Plain markdown for documentation

• JSON output for automation pipelines

• Grouped by type with user-readable descriptions

4. Quality Enforcement

• Commit message linter for CI and pre-commit hooks

• Strict mode that blocks non-conforming commits

• Scope validation against allowed values

• Breaking change documentation requirements

When to Use

• Before publishing a release tag

• During CI to generate release notes automatically

• In PR checks to enforce commit message standards

• In monorepos where package changelogs need scoped filtering

• When converting raw git history into user-facing notes

• As a pre-release checklist step

Conventional Commit Format

<type>(<scope>)<!>: <description>

[optional body]

[optional footer(s)]

Type to Section Mapping

Commit Type Changelog Section SemVer Bump User-Facing?

feat

Added minor Yes

fix

Fixed patch Yes

perf

Performance patch Yes

security

Security patch Yes

deprecated

Deprecated minor Yes

remove

Removed major Yes

refactor

Changed patch Sometimes

docs

— patch No

test

— — No

build

— — No

ci

— — No

chore

— — No

Breaking Change Rules

Breaking changes always trigger a major version bump regardless of type:

feat(api)!: remove deprecated v1 endpoints

BREAKING CHANGE: The /api/v1/* endpoints have been removed. Migrate to /api/v2/* before upgrading. See migration guide at docs/v2-migration.md.

Changelog Rendering

Keep a Changelog Format

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

1.4.0 - 2026-03-09

Added

• User can now export projects as CSV (#234)
• Dark mode support for dashboard (#228)

Fixed

• Pagination returning duplicate items on page boundaries (#231)
• Login form not showing validation errors on mobile (#229)

Performance

• Reduced dashboard load time by 40% with query optimization (#232)

Security

• Updated jsonwebtoken to 9.0.2 to fix CVE-2024-XXXX (#233)

1.3.2 - 2026-02-28

Fixed

• API rate limiter not resetting after window expiry (#227)

GitHub Release Notes Format

What's New

• CSV Export: Users can now export project data as CSV files (#234)
• Dark Mode: Dashboard fully supports dark mode (#228)

Bug Fixes

• Fixed pagination returning duplicate items on page boundaries (#231)
• Fixed login form validation on mobile devices (#229)

Performance

• Dashboard load time reduced by 40% through query optimization (#232)

Security

• Updated jsonwebtoken to patch CVE-2024-XXXX (#233)

Full Changelog: https://github.com/org/repo/compare/v1.3.2...v1.4.0

Generation Workflow

Step 1: Collect Commits

Get commits between two tags

git log v1.3.2..HEAD --pretty=format:'%H %s' --no-merges

Get commits with full body (for breaking change detection)

git log v1.3.2..HEAD --pretty=format:'%H%n%s%n%b%n---COMMIT_END---' --no-merges

Step 2: Parse and Classify

import re from dataclasses import dataclass from typing import Optional

@dataclass class ParsedCommit: hash: str type: str scope: Optional[str] description: str body: Optional[str] breaking: bool breaking_description: Optional[str]

COMMIT_PATTERN = re.compile( r'^(?P<type>feat|fix|perf|refactor|docs|test|build|ci|chore|security|deprecated|remove)' r'(?:((?P<scope>[^)]+)))?' r'(?P<breaking>!)?' r':\s*(?P<description>.+)$' )

def parse_commit(hash: str, message: str) -> Optional[ParsedCommit]: lines = message.strip().split('\n') subject = lines[0] body = '\n'.join(lines[1:]).strip() if len(lines) > 1 else None

match = COMMIT_PATTERN.match(subject)
if not match:
    return None  # Non-conventional commit

breaking = bool(match.group('breaking'))
breaking_desc = None

if body and 'BREAKING CHANGE:' in body:
    breaking = True
    bc_match = re.search(r'BREAKING CHANGE:\s*(.+)', body, re.DOTALL)
    if bc_match:
        breaking_desc = bc_match.group(1).strip()

return ParsedCommit(
    hash=hash,
    type=match.group('type'),
    scope=match.group('scope'),
    description=match.group('description'),
    body=body,
    breaking=breaking,
    breaking_description=breaking_desc,
)

Step 3: Determine Version Bump

def determine_bump(commits: list[ParsedCommit]) -> str: """Determine semver bump from parsed commits.""" if any(c.breaking for c in commits): return 'major' if any(c.type == 'feat' for c in commits): return 'minor' if any(c.type in ('fix', 'perf', 'security', 'refactor') for c in commits): return 'patch' return 'none'

def bump_version(current: str, bump: str) -> str: """Apply bump to a semver string.""" major, minor, patch = map(int, current.lstrip('v').split('.')) if bump == 'major': return f"{major + 1}.0.0" elif bump == 'minor': return f"{major}.{minor + 1}.0" elif bump == 'patch': return f"{major}.{minor}.{patch + 1}" return current

Step 4: Render Changelog

SECTION_MAP = { 'feat': 'Added', 'fix': 'Fixed', 'perf': 'Performance', 'security': 'Security', 'deprecated': 'Deprecated', 'remove': 'Removed', 'refactor': 'Changed', }

def render_changelog(version: str, date: str, commits: list[ParsedCommit], repo_url: str) -> str: sections: dict[str, list[str]] = {}

# Breaking changes get their own section
breaking = [c for c in commits if c.breaking]
if breaking:
    sections['BREAKING CHANGES'] = []
    for c in breaking:
        desc = c.breaking_description or c.description
        scope = f"**{c.scope}**: " if c.scope else ""
        sections['BREAKING CHANGES'].append(f"- {scope}{desc}")

# Group remaining by section
for commit in commits:
    section = SECTION_MAP.get(commit.type)
    if not section:
        continue
    if section not in sections:
        sections[section] = []
    scope = f"**{commit.scope}**: " if commit.scope else ""
    link = f"([{commit.hash[:7]}]({repo_url}/commit/{commit.hash}))"
    sections[section].append(f"- {scope}{commit.description} {link}")

# Render
lines = [f"## [{version}] - {date}", ""]
for section_name in ['BREAKING CHANGES', 'Added', 'Changed', 'Deprecated', 'Removed', 'Fixed', 'Performance', 'Security']:
    if section_name in sections:
        lines.append(f"### {section_name}")
        lines.extend(sections[section_name])
        lines.append("")

return '\n'.join(lines)

Commit Linting

Pre-Commit Hook

#!/bin/bash

.git/hooks/commit-msg

Validates commit message follows Conventional Commit format

COMMIT_MSG_FILE=$1 COMMIT_MSG=$(cat "$COMMIT_MSG_FILE") FIRST_LINE=$(head -1 "$COMMIT_MSG_FILE")

PATTERN='^(feat|fix|perf|refactor|docs|test|build|ci|chore|security|deprecated|remove)(([a-z0-9-]+))?!?:\s.{1,72}$'

if ! echo "$FIRST_LINE" | grep -qE "$PATTERN"; then echo "ERROR: Commit message does not follow Conventional Commits format." echo "" echo "Expected: <type>(<scope>): <description>" echo "Example: feat(auth): add OAuth2 login flow" echo "" echo "Valid types: feat, fix, perf, refactor, docs, test, build, ci, chore, security" echo "" echo "Your message: $FIRST_LINE" exit 1 fi

Check description length

DESC_LENGTH=$(echo "$FIRST_LINE" | sed 's/^[^:]*: //' | wc -c) if [ "$DESC_LENGTH" -gt 72 ]; then echo "ERROR: Commit description exceeds 72 characters ($DESC_LENGTH chars)." exit 1 fi

CI Linting

.github/workflows/lint-commits.yml

name: Lint Commits on: pull_request:

jobs: commitlint: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - uses: actions/setup-node@v4 with: node-version: 20 - run: npm install -g @commitlint/cli @commitlint/config-conventional - run: | npx commitlint --from ${{ github.event.pull_request.base.sha }}
--to ${{ github.event.pull_request.head.sha }}

Monorepo Strategy

Scoped Changelogs

In a monorepo, each package maintains its own changelog filtered by scope:

Get commits scoped to a specific package

git log v1.3.0..HEAD --pretty=format:'%H %s' --no-merges |
grep -E '^\w+ (feat|fix|perf|refactor)(ui):'

Example output:

abc1234 feat(ui): add date picker component

def5678 fix(ui): button alignment on mobile

Per-Package Changelog Location

packages/ ui/ CHANGELOG.md ← @repo/ui changes only package.json api/ CHANGELOG.md ← @repo/api changes only package.json CHANGELOG.md ← infrastructure / cross-cutting changes

Release Workflow Integration

PR merges to main │ v CI detects new commits since last tag │ v Parse commits → determine bump → generate changelog │ v Create draft GitHub Release with generated notes │ v Human reviews and edits release notes │ v Publish release → triggers deployment pipeline

Output Quality Checklist

Before publishing generated changelog:

• Each bullet is user-meaningful, not implementation noise

• Breaking changes include migration instructions

• Security fixes are in their own section (not mixed with bug fixes)

• Duplicate bullets across sections are removed

• Scope prefixes are consistent and meaningful

• Empty sections are omitted

• Links to PRs/commits are correct

Common Pitfalls

• Merge commit messages polluting the changelog — exclude merge commits with --no-merges

• Vague commit messages — "fix stuff" cannot become a useful release note; enforce linting

• Missing migration guidance for breaking changes — require BREAKING CHANGE: footer with instructions

• Docs/chore commits in user-facing changelog — filter to only user-facing types

• Overwriting historical entries — always prepend new entries, never modify existing ones

• Manual version bumps in monorepos — use Changesets for coordinated versioning

Best Practices

• Enforce conventional commits in CI — block merges with non-conforming messages

• Scope commits in monorepos — feat(ui): not just feat: for package-specific changes

• Review generated changelog before publishing — automation gets you 90%, human editing adds polish

• Tag releases after changelog is finalized — changelog is part of the release, not an afterthought

• Keep an [Unreleased] section — for manual curation between releases

• Link to PRs, not commits — PRs have context and discussion that commits lack

• Separate internal and external changelogs — users do not need to know about CI config changes