changelog-writer

Changelog Writer

Generate changelogs, release notes, breaking change summaries, migration guides, and version bump recommendations from git history.

Scope: Changelog and release documentation only. NOT for git operations (git-workflow), documentation sites (docs-steward), or code review (review).

Dispatch

$ARGUMENTS	Mode
Empty / generate	Generate changelog from recent commits
release <version>	User-facing release notes for specific version
breaking	Breaking change detection and summary
migration <from> <to>	Migration guide between two versions
bump	Semantic version recommendation based on changes
Unrecognized input	Ask for clarification, show mode menu

Canonical Vocabulary

Term	Definition
conventional commit	Commit following type(scope): description format
change type	Classification: feat, fix, refactor, perf, docs, chore, test, ci, build, style
breaking change	Backward-incompatible change, marked by ! or BREAKING CHANGE: footer
scope	Component affected, in parentheses after type
changelog entry	Formatted line item in a changelog section
release notes	User-facing summary of changes for a version
migration guide	Step-by-step instructions to upgrade between versions
semver bump	major (breaking), minor (feat), patch (fix) recommendation
unreleased	Changes since the last tagged version

Mode 1: Generate Changelog

Default mode. Produces a Keep a Changelog formatted document.

Step 1: Classify Commits

Run the commit classifier script:

uv run python skills/changelog-writer/scripts/commit-classifier.py [--since <tag-or-date>] [--until <ref>] [--path <dir>]

Parse the JSON output. The script classifies each commit by conventional type and detects breaking changes.

Step 2: Format Changelog

Run the changelog formatter script:

uv run python skills/changelog-writer/scripts/changelog-formatter.py --input <classified-json> [--format keepachangelog|github|simple]

The script converts classified commits to formatted markdown. Default format: Keep a Changelog.

Step 3: Review and Refine

• Group entries by section (Added, Changed, Deprecated, Removed, Fixed, Security)
• Rewrite terse commit messages into user-readable descriptions
• Merge related commits into single entries where appropriate
• Ensure breaking changes are prominently called out

Format reference: read references/changelog-conventions.md

Mode 2: Release Notes

release <version> produces polished, user-facing release notes.

Step 1: Identify Scope

Determine the range: last tag to HEAD (or between two tags if version already tagged).

git log --oneline <previous-tag>..<version-or-HEAD>

Step 2: Classify and Group

Run commit-classifier.py with the appropriate --since and --until flags. Group by user impact, not commit type:

• Highlights — headline features (top 3-5)
• Improvements — enhancements, performance gains
• Bug Fixes — resolved issues
• Breaking Changes — migration-required items (link to migration mode)
• Contributors — credit contributors from git log

Step 3: Write Release Notes

Rewrite technical commit messages into user-facing language. Reference: read references/changelog-conventions.md, section "Release Note Style."

Mode 3: Breaking Changes

breaking scans for backward-incompatible changes.

Step 1: Detect

Run the commit classifier with breaking-change focus:

uv run python skills/changelog-writer/scripts/commit-classifier.py --breaking-only [--since <tag>]

Step 2: Enrich

For each breaking change:

1. Identify the affected API/interface
2. Describe what changed and why
3. Provide the before/after code pattern
4. Assess blast radius (how many consumers affected)

Use patterns from data/breaking-change-patterns.json for language-specific detection.

Step 3: Summarize

Output a breaking changes report with severity ranking (high/medium/low) based on blast radius and migration effort.

Mode 4: Migration Guide

migration <from> <to> generates step-by-step upgrade instructions.

Step 1: Collect Breaking Changes

Run commit classifier between the two versions:

uv run python skills/changelog-writer/scripts/commit-classifier.py --breaking-only --since <from> --until <to>

Step 2: Generate Migration Steps

For each breaking change, produce:

1. What changed — old behavior vs new behavior
2. Action required — exact steps to migrate
3. Code example — before/after snippets
4. Verification — how to confirm the migration worked

Order steps by dependency (changes that must happen first go first).

Step 3: Compile Guide

Structure as a numbered checklist. Include a pre-migration checklist (backup, test suite green) and post-migration verification steps.

Reference: read references/changelog-conventions.md, section "Migration Guide Structure."

Mode 5: Version Bump

bump recommends the next semantic version.

Step 1: Analyze

Run the commit classifier:

uv run python skills/changelog-writer/scripts/commit-classifier.py --since <last-tag>

Read the suggested_bump field from the JSON output.

Step 2: Report

Present the recommendation with evidence:

Bump	Reason
major	Breaking changes detected: list them
minor	New features without breaking changes
patch	Bug fixes and non-functional changes only

Show the commit evidence supporting the recommendation. If commits are ambiguous (non-conventional format), flag uncertainty and ask for confirmation.

Reference Files

Load ONE reference at a time.

File	Content	Read When
references/changelog-conventions.md	Keep a Changelog format, release note style, migration guide structure, semver decision tree	Formatting output in any mode
references/commit-parsing.md	Conventional commits parsing rules, breaking change detection heuristics	Understanding classifier output or edge cases

Data File	Content	Used By
data/changelog-formats.json	Format templates (Keep a Changelog, GitHub Releases, simple)	changelog-formatter.py
data/breaking-change-patterns.json	Language-specific breaking change detection patterns	commit-classifier.py, Mode 3 enrichment

Script	Purpose
scripts/commit-classifier.py	Parse git log, classify by conventional type, detect breaking changes
scripts/changelog-formatter.py	Convert classified commits JSON to formatted changelog markdown

Critical Rules

1. Never modify git history or run git operations beyond git log and git tag — this skill reads only
2. Always run commit-classifier.py before formatting — do not manually parse git log
3. Breaking changes must be prominently called out in every output format
4. Rewrite commit messages into user-readable language — raw commit text is not a changelog
5. Migration guides must include before/after code examples for every breaking change
6. Version bump recommendations must cite specific commits as evidence
7. When commits are non-conventional, classify by best-effort heuristics and flag uncertainty
8. Do not generate changelogs for uncommitted changes — only committed history
9. Always identify the previous tag as the baseline unless the user specifies otherwise
10. Credit contributors in release notes — extract from git log author fields