Keep a Changelog Format: Complete Guide
Comprehensive guide to the Keep a Changelog format for release notes. Covers the six standard categories, header format, and compliance with the specification.
Templates
Detailed Explanation
Keep a Changelog Format
Keep a Changelog is the most widely adopted standard for formatting changelogs and release notes. It provides a consistent structure that makes changelogs readable for both humans and machines.
Header Format
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
## [1.1.0] - 2026-02-28
### Added
- New feature descriptions here
### Changed
- Modifications to existing features
### Deprecated
- Features that will be removed in future versions
### Removed
- Features that were removed in this version
### Fixed
- Bug fixes
### Security
- Vulnerability patches
The Six Categories
| Category | When to Use |
|---|---|
| Added | New features, new APIs, new CLI commands |
| Changed | Modifications to existing behavior, updated dependencies |
| Deprecated | Features marked for future removal (still works, but warned) |
| Removed | Features that were deleted in this version |
| Fixed | Bug fixes, corrections to existing behavior |
| Security | Vulnerability patches, security improvements |
Rules
- Each version gets its own section with a date
- Categories appear only if they have entries (omit empty categories)
- Versions are listed in reverse chronological order (newest first)
- The
[Unreleased]section collects upcoming changes - Use ISO 8601 date format (YYYY-MM-DD)
- Link version headers to diff URLs when possible
Anti-Patterns to Avoid
- Dumping raw git commit messages
- Using inconsistent date formats
- Including internal ticket numbers without descriptions
- Writing from the developer's perspective instead of the user's
Use Case
Setting up a changelog for a new open-source project or migrating an existing unstructured changelog to the Keep a Changelog standard for better readability and consistency.