Guide
Keep a Changelog format, explained with a copy-paste template
Keep a Changelog is a widely used convention for writing a CHANGELOG.md file by hand. Olivier Lacan started it, and the current version of the guide is 1.1.0. You can copy the template further down, then turn the finished file into a changelog page your users can read.
The idea behind the format
The format starts from the rule that people read changelogs, so you write them for people. A commit log records each step a developer took, while a changelog lists the changes a user or another developer needs to know about, grouped so they can find them quickly. Each version has its own entry with its release date, and the newest version goes at the top.
Types of changes
Each version lists its changes under a small set of headings, and you only include the headings that apply to that release.
- Added, for new features.
- Changed, for changes to existing functionality.
- Deprecated, for features that will be removed soon.
- Removed, for features that are gone.
- Fixed, for bug fixes.
- Security, for vulnerability fixes.
Keep upcoming changes at the top
Keep a section called Unreleased at the top of the file and add to it as changes merge, which lets people see what is coming. When you cut a release you rename that section to the new version number and add the date, and the notes are ready the moment you ship.
Dates and versions
Write dates as year, month and day, like 2026-11-20. That order reads the same in every country and sorts correctly. The guide also asks you to state whether the project follows Semantic Versioning. That tells readers what a version bump means for them.
Yanked releases
If you pull a version because of a serious bug or a security problem, keep its entry and add the YANKED tag after the date. Readers can then see that the version exists and that they should avoid it.
Template to copy
# Changelog
All notable changes to this project are documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
## [Unreleased]
### Added
- Short description of a new feature.
## [1.2.0] - 2026-11-20
### Added
- Export any project as CSV from the Settings page.
### Changed
- The dashboard now loads the last 30 days by default.
### Fixed
- Search results no longer repeat the same item twice.
## [1.1.0] - 2026-10-02
### Removed
- The legacy v1 API. Move to v2 before upgrading.
Common mistakes
Pasting a git log into the file is the most common one, because merge commits and internal notes make the changes readers care about hard to find. Skipping deprecations is the second, since people upgrading need to see what will break before it breaks. Leaving out dates makes it hard to match a change to something a user noticed.
From CHANGELOG.md to a page your users see
Most users never open your repository, so a CHANGELOG.md mostly reaches contributors. Our free CHANGELOG.md tool reads the file from a public GitHub repo and turns each version into its own entry, with your dates and your Added, Changed and Fixed groups kept as they are. You don't need an account to see the result.
Turn your CHANGELOG.md into a page
If you want to host it, ShipLog imports those entries into a public changelog page and an in-app widget with a "what's new" badge. The free plan keeps 10 entries, and Captain is $9 a month per project.
For release notes aimed at customers rather than developers, see how to write release notes and the release notes templates .