Conventional Changelog Format Guide
Guide to the Conventional Changelog format used by standard-version and semantic-release. Covers commit type mapping, scope grouping, and automated generation.
Templates
Detailed Explanation
Conventional Changelog Format
The Conventional Changelog format is designed to be generated automatically from Conventional Commits. It maps commit types to changelog categories and groups changes by scope.
Generated Output Structure
# 1.5.0 (2026-02-28)
### Features
* **auth:** add OAuth2 PKCE flow support (a1b2c3d)
* **api:** implement rate limiting middleware (d4e5f6a)
* **cli:** add `--dry-run` flag to deploy command (b7c8d9e)
### Bug Fixes
* **auth:** fix token refresh race condition (f1a2b3c)
* **api:** correct content-type for multipart uploads (e4d5c6b)
* **database:** resolve deadlock in concurrent writes (a7b8c9d)
### Performance Improvements
* **renderer:** reduce bundle size by 40% with tree shaking (c1d2e3f)
### BREAKING CHANGES
* **auth:** The `login()` function now requires an options object.
Before: `login(user, pass)`
After: `login({ username: user, password: pass })`
Commit Type to Category Mapping
| Commit Type | Changelog Category | SemVer Bump |
|---|---|---|
feat: |
Features | Minor |
fix: |
Bug Fixes | Patch |
perf: |
Performance Improvements | Patch |
revert: |
Reverts | Patch |
docs: |
(usually excluded) | None |
style: |
(usually excluded) | None |
refactor: |
(usually excluded) | None |
test: |
(usually excluded) | None |
chore: |
(usually excluded) | None |
BREAKING CHANGE: |
Breaking Changes | Major |
Tools for Automation
- standard-version: Bump version, generate changelog, create git tag
- semantic-release: Fully automated — determines version from commits, publishes to npm
- conventional-changelog-cli: Generate changelog only, no version bumping
Configuration
{
"preset": "angular",
"types": [
{ "type": "feat", "section": "Features" },
{ "type": "fix", "section": "Bug Fixes" },
{ "type": "perf", "section": "Performance" },
{ "type": "revert", "section": "Reverts" }
]
}
When to Use This Format
- Projects that follow Conventional Commits strictly
- Teams using automated release pipelines
- Monorepos where scope grouping helps distinguish packages
Use Case
Setting up automated changelog generation in a CI/CD pipeline using tools like semantic-release or standard-version, where Conventional Commits drive both versioning and changelog content.