changelog-generator

---
name: changelog-generator
description: Use when generating release notes from Conventional Commits, computing semantic version bumps, cutting releases, or planning hotfixes.
category: Engineering
version: 1.0.0
tools: []
---

# Changelog Generator

Produce consistent, auditable release notes from Conventional Commits. Separates parsing, semantic-bump logic, and rendering for automated releases with editorial control.

## Core Capabilities

- Parse Conventional Commits using standard rules
- Detect semantic bump: major, minor, patch from commit stream
- Render Keep a Changelog sections: Added, Changed, Fixed, Deprecated, Security, Removed, etc.
- Generate release entries from git ranges or commit input
- Enforce format via linter script
- Support CI integration with JSON output for automation

## When to Use

- Before publishing a release tag
- During CI to generate release notes automatically
- During PR checks to block invalid formats
- In monorepos requiring scoped filtering by package
- Converting git history into user-facing notes
- Planning hotfixes with minimal change scope

## Conventional Commit Rules

Supported types: feat, fix, perf, refactor, docs, test, build, ci, chore, security, deprecated, remove

Breaking changes:
- `type(scope)!: summary`
- Footer/body includes `BREAKING CHANGE:`

SemVer mapping:
- breaking → major
- non-breaking feat → minor
- all others → patch

## Scripts

- **generate_changelog.py**: Read commits from git/stdin; render markdown/JSON; optional in-place prepend
- **commit_linter.py**: Validate format; return non-zero in --strict mode on violations
- **version_bumper.py**: Derive next version from commits; output includes recommended_version, bump_type, exact git tag commands; accepts --prerelease alpha|beta|rc

## Common Pitfalls

1. Mixing merge commits with release parsing
2. Vague summaries that cannot become user-facing notes
3. Missing migration guidance for breaking changes
4. Treating docs/chore as user-facing features
5. Overwriting historical sections instead of prepending
6. Not filtering scope in monorepos by package name

## Best Practices

1. Keep commits small and intent-driven
2. Use scopes aligned to package names in monorepos
3. Enforce linter in PR pipelines
4. Review generated markdown before publishing
5. Tag releases only after changelog generation succeeds
6. Keep [Unreleased] section for manual curation when needed
7. Document breaking changes with migration action

## Hotfix Severity & SLAs

| Severity | Definition | SLA | Approval |
|---|---|---|---|
| P0 — Critical | Outage, data loss, exploited vulnerability | ≤ 2h | Engineering Lead + On-call |
| P1 — High | Major feature broken, significant user impact | ≤ 24h | Engineering Lead + Product Manager |
| P2 — Medium | Minor issues, limited impact | Next release cycle | Standard PR review |

Hotfix branch comes from last stable tag. Contains minimal fix only. Gets own patch-bump changelog entry.

## Rollback Triggers

Roll back when any threshold fires:

| Trigger | Threshold |
|---|---|
| Error rate spike | > 2x baseline within 30 min |
| Latency increase | > 50% degradation |
| Feature failure | Core broken |
| Security incident | Being exploited |
| Data corruption | Database integrity compromised |

Prefer feature-flag disable over code rollback. Database rollbacks only for non-destructive migrations (forward-only migrations preferred).

## Release Governance

Use this flow for predictability:

1. Lint commit history for target release range
2. Generate changelog draft from commits
3. Manually adjust wording for customer clarity
4. Validate semver bump recommendation
5. Tag release only after changelog approved

## Output Quality Checks

- Each bullet is user-meaningful, not implementation noise
- Breaking changes include migration action
- Security fixes isolated in Security section
- Sections with no entries are omitted
- Duplicate bullets removed across sections

## CI Policy

- Run commit_linter.py --strict on all PRs
- Block merge on invalid conventional commits
- Auto-generate draft release notes on tag push
- Require human approval before writing into CHANGELOG.md on main branch

## Monorepo Guidance

- Prefer commit scopes aligned to package names
- Filter commit stream by scope for package-specific releases
- Keep infra-wide changes in root changelog
- Store package changelogs near package roots for ownership clarity