What does the Keep a Changelog format look like?
Keep a Changelog is a community convention, not a tool. It started as a short guide published at keepachangelog.com and spread through open source projects because it is easy to follow. The guide describes one Markdown file, usually named CHANGELOG.md, that lives at the root of a repository.
The file has a strict shape. A short intro says the project follows the convention. An Unreleased section sits at the top and collects changes that have merged but not yet shipped. Below it, every released version has a heading in the form [1.4.0] - 2026-03-02, with the newest version first. Dates use the ISO format so they read the same in every country.
Inside each version, entries are grouped under six headings, and only those six:
- Added for new features
- Changed for changes to existing behavior
- Deprecated for features that will be removed soon
- Removed for features that are now gone
- Fixed for bug fixes
- Security for vulnerability fixes
Version numbers follow semantic versioning, and each version heading links to a diff between it and the previous tag. The guide also states its core principle plainly: a changelog is written for humans, not machines, and a raw git log is not a changelog.
Why does the Keep a Changelog format matter?
The format solves a reading problem. When every project structures its history the same way, a developer evaluating an upgrade can scan for the one section that matters. Someone worried about a breaking change jumps to Changed and Removed. Someone patching a vulnerability jumps to Security.
It also solves a writing problem. Six fixed categories remove the daily debate about how to phrase an entry. The Unreleased section gives engineers a place to log a change in the same pull request that makes it, so the record is never rebuilt from memory at release time.
For product and customer success teams, the value is trust. A customer who finds a consistent, dated, versioned record of every change tends to believe the rest of what the company says. A deprecation notice that appears in the Deprecated section one version before removal gives customers a fair warning and gives support a page to point to.
The format has limits. It assumes numbered releases, which many continuously deployed SaaS products no longer have. It is written in a developer's voice and lives in a code repository, so non-technical customers rarely see it. Those limits shape how the format is used outside open source, as covered below.
Examples of the Keep a Changelog format
The clearest example is the convention's own CHANGELOG.md, which documents changes to the guide using the exact structure it prescribes.
Many open source libraries on GitHub adopt the format and say so in the first line of their changelog. A typical entry reads like this:
[2.3.0] - 2026-01-15
- Added: Export reports as CSV from the dashboard
- Fixed: Date filter ignored the selected timezone
A SaaS API team often keeps a CHANGELOG.md in the format for its SDK or client library, while publishing a plain-language product update for end users. The two documents describe the same release at different altitudes.
Internal platform teams use the format for shared services other engineers consume. Here the Deprecated and Removed sections do the heaviest work, because downstream teams plan their migrations from them. Our changelog template guide walks through more variations.
How to write a changelog in the Keep a Changelog format
- Create CHANGELOG.md at the repository root. State in the intro that the file follows Keep a Changelog and semantic versioning.
- Keep an Unreleased section at the top. Ask every pull request that changes behavior to add one line under it. This is the habit that makes the format work.
- Write entries for people, not machines. Describe the effect on the user, not the commit. "Fixed date filter ignoring the timezone" beats "refactored DateFilter."
- Use only the six categories. If an entry does not fit, it probably needs to be split or rewritten. Do not invent new headings.
- On release, rename Unreleased to the version and date. Use ISO dates such as 2026-09-15 and start a fresh Unreleased section above it.
- Link each version heading to a diff. Comparison links let reviewers see the actual code behind a line.
- Call out breaking changes and deprecations early. A change that lands in Deprecated should reappear in Removed in a later version, never as a surprise.
- Never rewrite published history. If a release was wrong, note it in a later entry rather than editing the old one.
If your team ships continuously, keep the categories and the human voice but key entries by date instead of version. Our post on changelog versioning covers how to choose between the two.
Keep a Changelog vs. release notes and other neighbors
The most common mistake is treating the format as a customer-facing channel. It is a developer record. Release notes are the narrative layer on top: they explain why a change matters, show a screenshot, and are written for the people who buy and use the product. Most SaaS teams need both, and the difference between a changelog and release notes is worth settling early.
A second mistake is pasting the git log into the file. Commit messages are written for reviewers, in the order code landed, and full of noise. The guide explicitly rejects this practice. Auto-generating a draft from commits is fine; publishing it unedited is not. See changelog automation for where tooling helps and where a human still edits.
Other frequent errors include mixing date formats, skipping the Unreleased section and reconstructing the list at release time, and silently removing a feature without a prior Deprecated entry. Semantic versioning is a related but separate convention: it governs the version number, while Keep a Changelog governs the text under it. Read the full Keep a Changelog walkthrough for a deeper comparison.
How AnnounceKit handles keep a Changelog format
AnnounceKit is the customer-facing layer that sits above a CHANGELOG.md. Teams keep the developer record in the repository and publish the human version on a changelog page on their own domain. The same post can appear in 10+ in-app widget display modes, go out as an email digest, and post to Slack.
AI post generation turns a raw list of changes into a draft your product marketer can edit, and the official MCP server lets AI agents create and publish posts as part of a release pipeline. Segmentation targets the right customers with each update, while feature requests with voting and Jira sync, plus NPS surveys, close the loop after a release. Pricing is flat per project from $79/month with a 15-day free trial.