Changelog Composer

Reference Files

references/conventional-commits.md

references/categorization-rules.md

references/audience-filter.md

references/changelog-formats.md

Prerequisites

• git — access to the repository history
• gh (optional) — GitHub CLI for PR description extraction
• A tagging strategy (semver tags) for identifying release boundaries

Workflow

Phase 1: Gather Raw Changes

1. Identify boundaries — Find the last release tag:

   git describe --tags --abbrev=0

   . If no tags exist, use the initial commit or a user-specified starting point.
2. Extract commits —

   git log <last-tag>..HEAD --oneline --no-merges

3. Extract PR titles —

   gh pr list --state merged --base main --search "merged:>YYYY-MM-DD"

   or parse merge commit messages.
4. Parse conventional commits — If the repository follows conventional commits (

   feat:

   ,

   fix:

   ,

   docs:

   , etc.), extract type, scope, and description. See

   references/conventional-commits.md

   .
5. Collect breaking change indicators — Look for

   BREAKING CHANGE:

   in commit bodies,

   !

   after type (

   feat!:

   ), or explicit annotations in PR descriptions.

Phase 2: Classify Changes

feat!:

BREAKING CHANGE:

feat:

fix:

perf:

docs:

chore:

ci:

refactor:

test:

build:

Phase 3: Filter for Audience

1. Exclude internal changes by default:
   • CI/CD configuration changes
   • Test additions/modifications
   • Dependency bumps (unless security-relevant)
   • Code refactoring with no behavior change
   • Build system changes
2. Include internal changes only when:
   • They represent significant architecture shifts users should know about
   • They affect development workflow (contributing guide changes)
   • The changelog targets developers, not end-users
3. Highlight breaking changes prominently — always at the top, always with migration guidance.

Phase 4: Compose Entries

1. Lead with the impact — "Users can now..." or "Fixed issue where..."
2. Be specific — "Reduced memory usage by 40% for large file processing" not "Performance improvements"
3. Include migration guidance for breaking changes — what the user must change
4. Link to source — PR number, issue number, or commit hash

Phase 5: Output

1. Breaking Changes (always first)
2. Features
3. Fixes
4. Performance
5. Documentation

Output Format

## [{version}] - {YYYY-MM-DD}

### Breaking Changes
- **`function_name` parameter renamed** — `old_param` is now `new_param`.
  Migration: find/replace `old_param=` with `new_param=` in all call sites. ([#{pr}]({url}))

### Features
- **{Feature name}** — {What it enables and why it matters}. ([#{pr}]({url}))

### Fixes
- Fixed {symptom} when {condition}. ([#{pr}]({url}))

### Performance
- {Operation} is now {X}x faster / uses {X}% less memory. ([#{pr}]({url}))

### Documentation
- Added {guide/reference} for {topic}. ([#{pr}]({url}))

Configuring Scope

release

sprint

pr

Calibration Rules

1. User impact first. Every entry should answer "what does this mean for the user?" not "what did the developer do?"
2. Breaking changes are non-negotiable. Never omit or bury breaking changes. They go first, with migration guidance.
3. Specific over vague. "Fixed login timeout on slow connections" beats "Fixed bug." "Added CSV export for reports" beats "New feature."
4. Link everything. Every entry links to its source PR or issue. Users who want details can follow the link.
5. Exclude noise. Internal refactoring, dependency bumps, and CI changes do not belong in user-facing changelogs unless they have user-visible impact.

Error Handling

--no-merges

When NOT to Compose

• The user wants to auto-publish release notes without review — changelogs require human judgment
• The repository has no meaningful commit history (single "initial commit" with everything)
• The request is for marketing copy, not technical release notes — different skill
• The changes are not yet merged — changelog is for shipped changes, not in-progress work