Keep a Changelog: The Standard Format Explained

If you've ever looked at a well-maintained open source project and noticed a clean, readable CHANGELOG.md, there's a good chance it follows the Keep a Changelog format.

Created by Olivier Lacan in 2014, Keep a Changelog established a simple, opinionated standard for how software changelogs should be written. It's hosted at keepachangelog.com and has been adopted by thousands of projects.

Here's everything you need to know.

The core principle

The guiding philosophy of Keep a Changelog is captured in its first principle:

"Don't let your friends dump git logs into changelogs."

A raw git log is a record for developers. A changelog is a record for users. They are not the same thing, and they should never be treated as the same thing.

The format

A Keep a Changelog file looks like this:

# Changelog

All notable changes to this project will be documented in this file.

## [Unreleased]

## [1.1.0] - 2026-02-01

### Added
- New user dashboard with activity feed
- CSV export for all reports

### Fixed  
- Login redirect loop when session expires
- Incorrect totals in monthly summary view

## [1.0.0] - 2026-01-01

### Added
- Initial release

The structure is simple:

• File header — title and a one-line description of what the file is
• [Unreleased] section — changes that are merged but not yet released
• Versioned sections — each release gets its own section with a date
• Change types — grouped by what kind of change they are

The change types

Keep a Changelog defines six types:

Type	When to use it
Added	New features
Changed	Changes to existing features
Deprecated	Features that will be removed
Removed	Features that were removed
Fixed	Bug fixes
Security	Security fixes

You only include types that have entries. A bugfix release might only have a Fixed section. A feature release might only have Added and Changed.

The [Unreleased] section

The [Unreleased] section is one of the most useful parts of the format. As changes land — PRs get merged, features ship to staging — you add bullets to [Unreleased].

When it's time to release, you:

1. Add a new version header below [Unreleased]
2. Move all the bullets down to the new version section
3. Add the release date
4. Leave [Unreleased] empty, ready for the next batch

This approach makes changelogs a living document throughout development, not a scrambled afterthought at release time.

Version links

Keep a Changelog recommends linking each version header to a diff on your version control system. At the bottom of the file:

[Unreleased]: https://github.com/yourorg/yourrepo/compare/v1.1.0...HEAD
[1.1.0]: https://github.com/yourorg/yourrepo/compare/v1.0.0...v1.1.0
[1.0.0]: https://github.com/yourorg/yourrepo/releases/tag/v1.0.0

This lets technically-inclined users click through to see exactly what changed at the code level, without cluttering the user-facing changelog.

What Keep a Changelog doesn't tell you

The format is excellent for open source libraries and developer tools. For SaaS products, a few adaptations are common:

Hosted instead of in a repo. A CHANGELOG.md in a GitHub repo is fine for developers who live there. For a SaaS product with non-technical users, a hosted changelog page on your website is more accessible.

User language instead of technical language. Keep a Changelog's format works for any writing style, but the principle of writing for users — not developers — deserves more emphasis for consumer and business software.

Notifications. A static file doesn't tell your users when something new is available. A hosted changelog can include an RSS feed or email subscription, turning it into a communication channel.

Is it right for your project?

Keep a Changelog is a great default for:

• Open source libraries and frameworks
• Developer tools with technical users
• Any project where contributors need to understand what's changed

For SaaS products with non-technical users, the format works well as a structural foundation — but pair it with user-friendly writing and a hosted page that's easy to find.

The underlying principles are universal: be consistent, write for your audience, don't use git logs as changelog content, and document changes when they happen rather than all at once later.

Those principles will serve you regardless of what format you use.