Use it for a CHANGELOG.md that lives next to your code and grows with every release. If you need to announce a single release to customers, with highlights, upgrade steps, and known issues, use the release notes template instead.
Need it as a document? Paste the filled-in template into the free Markdown to Word or Markdown to PDF converter.
Changelog key facts
- Name the file
CHANGELOG.mdand keep it in the repository root. Keep a Changelog notes that some projects useHISTORY,NEWS, orRELEASES. - List the latest version first, with an entry for every released version.
- Write dates as
YYYY-MM-DD(ISO 8601), for example## [1.4.0] - 2026-10-16. - Group changes under six types: Added, Changed, Deprecated, Removed, Fixed, Security.
- Keep an
## [Unreleased]section at the top and move its entries into a new version section at release time. - State whether the project follows Semantic Versioning.
- Write entries for people, not machines. A commit log is not a changelog.
Copyable Markdown CHANGELOG.md template
# 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]
### Added
- [New feature, in one line that a user can understand]
### Changed
- [Change to existing behavior]
### Deprecated
- [Feature that will be removed in a future version, and what to use instead]
### Removed
- [Feature removed in this version]
### Fixed
- [Bug fixed, described by the behavior users saw]
### Security
- [Vulnerability fixed, with an advisory or CVE link if one exists]
## [1.1.0] - YYYY-MM-DD
### Added
- [New feature]
### Fixed
- [Bug fix]
## [1.0.0] - YYYY-MM-DD
### Added
- [First stable release. Summarize the main capabilities.]
[unreleased]: https://github.com/[owner]/[repository]/compare/v1.1.0...HEAD
[1.1.0]: https://github.com/[owner]/[repository]/compare/v1.0.0...v1.1.0
[1.0.0]: https://github.com/[owner]/[repository]/releases/tag/v1.0.0
The six types of changes
Keep a Changelog defines a fixed set of headings so readers can scan any project's file the same way:
| Heading | Use it for |
|---|---|
| Added | New features |
| Changed | Changes in existing functionality |
| Deprecated | Features that will be removed in a future version |
| Removed | Features removed in this version |
| Fixed | Bug fixes |
| Security | Fixes for vulnerabilities |
Include only the headings that have entries for a given version. An empty ### Removed under every release adds noise.
How to maintain the Unreleased section
Add an entry to ## [Unreleased] in the same pull request that makes the change. The person who wrote the change knows best what it does for users, and the entry is reviewed with the code.
At release time, rename the Unreleased heading to the new version and date, add a fresh empty ## [Unreleased] above it, and update the link references at the bottom of the file. This keeps the release step mechanical: the content was written as the work happened.
Version numbers and Semantic Versioning
If the project follows Semantic Versioning 2.0.0, the version number signals the kind of change:
- MAJOR (2.0.0): incompatible API changes.
- MINOR (1.1.0): new functionality that is backward compatible.
- PATCH (1.0.1): backward compatible bug fixes.
Under SemVer, versions below 1.0.0 are for initial development, and the public API should not be considered stable. Marking public API functionality as deprecated calls for at least a minor version increase. If a version has a breaking change, say so plainly in its Changed or Removed entries, because a reader scanning the changelog before upgrading is looking for exactly that.
If the project does not follow SemVer, remove that line from the header and describe the versioning scheme you do use.
Linkable versions and yanked releases
Each version heading in brackets, such as ## [1.1.0], is a Markdown reference link. The definitions at the bottom of the file point each version to a comparison between tags, so a reader can click through to the exact code changes. Keep a Changelog recommends that versions and sections be linkable.
If a release is pulled because of a serious bug or security issue, keep its section and mark it, for example ## [0.0.5] - 2014-12-13 [YANKED]. Deleting the section hides history that readers may need.
Common changelog mistakes
- Pasting
git logoutput. Commit messages describe code changes for maintainers, not outcomes for users. - Leaving out deprecations, so users meet a removal with no warning.
- Using regional date formats such as
10/11/2026, which readers interpret differently. - Recording only some changes, so readers cannot trust the file as a complete list of notable changes.
Completed changelog example
## [2.0.0] - 2026-10-16
### Changed
- The `export` command now writes UTF-8 by default. Pass `--encoding latin-1`
to keep the previous behavior.
### Removed
- The `--legacy-parser` flag, deprecated in 1.6.0.
### Fixed
- Headers containing commas are no longer split into two columns.
## [1.6.0] - 2026-08-02
### Deprecated
- The `--legacy-parser` flag. It will be removed in 2.0.0.
The breaking change is described from the user's side, with the option that restores the old behavior. The removal in 2.0.0 was announced as a deprecation in an earlier version, so users had warning. The version numbers and dates are illustrative.
What to include in a changelog
| Element | What to write |
|---|---|
| Title and intro | # Changelog, a one-line description, and the formats followed |
| Unreleased | Changes merged but not yet released |
| Version heading | ## [version] - YYYY-MM-DD, newest first |
| Change groups | Added, Changed, Deprecated, Removed, Fixed, Security |
| Entries | One line per notable change, written for users |
| Breaking changes | What changed and what users must do |
| Link references | Compare links for each version at the bottom |
Changelog FAQ
What is the difference between a changelog and release notes?
A changelog is a cumulative file in the repository that records notable changes for every version, usually for developers and users of a library or tool. Release notes describe one release for its audience, often with highlights, upgrade steps, and known issues. Many teams write release notes from the changelog entries.
Should every commit go in the changelog?
No. Include notable changes that affect users: new features, behavior changes, deprecations, removals, bug fixes, and security fixes. Internal refactoring and test changes usually stay in version control history.
Can I generate a changelog automatically?
Tools can collect entries from commit messages or pull request labels. The result is only as useful as those inputs. Review generated entries and rewrite them for readers before release.
Where do I put the changelog?
In the repository root as CHANGELOG.md, so it is easy to find next to README.md.
Do I have to use Semantic Versioning to use Keep a Changelog?
No. Keep a Changelog asks you to state whether you follow Semantic Versioning. The format works with any versioning scheme.
Related templates
- Release notes template
- README template
- CONTRIBUTING.md template
- Bug report template
- All Markdown templates