The Keep a Changelog format, explained with examples
A guide to the Keep a Changelog standard — its categories, semantic versioning, and how to apply the format to a real changelog.
If you have looked into changelog conventions, you have probably come across "Keep a Changelog" — the most widely adopted format for software changelogs. This guide explains the Keep a Changelog format, its categories, and how to apply it in practice.
What is Keep a Changelog?
Keep a Changelog is a simple, popular convention for structuring a changelog file
(usually CHANGELOG.md). Its goal is to make changelogs readable by humans, not
just machines, with a consistent set of categories and ordering rules.
The standard categories
Each release groups its changes under a fixed set of headings:
- Added — new features.
- Changed — changes to existing functionality.
- Deprecated — features that will be removed soon.
- Removed — features removed in this release.
- Fixed — bug fixes.
- Security — changes that address vulnerabilities.
You only include the categories that apply to a given release.
A minimal example
## [1.4.0] - 2026-05-01
### Added
- Weekly email digest of new changelog entries.
### Fixed
- Long file names no longer break imports.
### Security
- Patched an issue in token validation.
Semantic versioning
Keep a Changelog pairs naturally with semantic versioning (MAJOR.MINOR.PATCH):
- MAJOR for breaking changes.
- MINOR for new, backward-compatible features.
- PATCH for backward-compatible bug fixes.
Together they tell readers not just what changed, but how much.
The "Unreleased" section
A common practice is to keep an Unreleased heading at the top where changes
accumulate before a version is cut. When you release, you rename it to the new
version and start a fresh Unreleased block.
The format is only half the job — the entries still have to be written for humans.
From developer format to customer changelog
Keep a Changelog is excellent for developer-facing project files. For a customer-facing public changelog, you typically want friendlier categories like New, Improved, and Fixed. Changelog Generator can take the work captured in your merged pull requests and produce both — a structured developer changelog and a polished customer-facing one — without rewriting everything twice.