Keep a Changelog Format
Learn how to generate a CHANGELOG.md following the Keep a Changelog specification with Added, Changed, Fixed, and Removed sections.
Detailed Explanation
The Keep a Changelog Standard
Keep a Changelog is the most widely adopted convention for structuring changelogs. It groups changes under standardized section headings that communicate the nature of each change at a glance.
Section Mapping
When using the Keep a Changelog format, Conventional Commit types are mapped to the standard sections:
| Commit Type | Keep a Changelog Section |
|---|---|
feat |
Added |
fix |
Fixed |
perf, refactor, docs, style, build, ci, chore, test |
Changed |
revert |
Removed |
Output Structure
# Changelog
All notable changes to this project will be documented in this file.
## [1.2.0] - 2026-02-27
### Added
- **auth:** add OAuth2 login with Google
- add dark mode toggle to settings page
### Fixed
- **auth:** resolve token refresh race condition
- prevent crash when config file is missing
### Changed
- upgrade TypeScript to 5.4
- update API authentication guide
Why Keep a Changelog?
The specification was designed for human readers, not machines. It emphasizes clear categorization and discourages dumping raw commit messages. By mapping Conventional Commits to its sections, the generator bridges the gap between developer-friendly commit messages and user-friendly release notes. The preamble text and formatting conventions are automatically included so the resulting file is immediately compliant with the specification.
Use Case
Ideal for open-source projects that follow the Keep a Changelog convention. Contributors and users can scan the Added and Fixed sections to understand what changed in each release without reading raw commit logs.