Changelog Automation

Auto-generate changelogs from commits.

Conventional commits

Standard commit message format: type(scope): subject. Types include feat, fix, docs, refactor, test, chore.

Tools parse these conventions. semantic-release, conventional-changelog, release-please all expect this format.

Adoption requires team discipline. Linting hooks (commitlint) catch deviations at commit time. CI rejects PRs with malformed messages.

Generation tools

semantic-release: full automation. Determines version bump from commit types, generates changelog, publishes release.

conventional-changelog: changelog only. Suitable when version bumping is manual or version comes from another source.

release-please: GitHub native. Creates a release PR that accumulates changes; merge to release. Good middle ground.

Release process integration

On main merge: tool computes version, generates changelog entry, creates GitHub release. All automatic.

Tag follows semver: MAJOR for breaking changes (BREAKING CHANGE: footer), MINOR for features, PATCH for fixes.

Changelog committed to CHANGELOG.md or only in releases. Either works; commit-to-file is more searchable.

Audience-specific changelogs

Internal changelog: full detail, every change. Useful for engineering teams and support.

Customer-facing changelog: filtered. Only customer-relevant changes; plain language; grouped by feature area.

Two artifacts; same source. Internal is full conventional-changelog output; customer version is curated by product or marketing.

Pitfalls

Inconsistent commit conventions. The tool produces nonsense if commits don't follow the format. Linting at commit time is mandatory.

Missing breaking-change footers. Tool can't detect a breaking change; semver versioning gets it wrong; downstream breaks unexpectedly.

Over-detailed customer changelogs. Customers don't care about refactors. Curate aggressively; show only what matters to them.