Keep a Changelog: Best Practices and Tools (keepachangelog.com)

If your team has ever argued about CHANGELOG.md format, you have met the Keep a Changelog spec whether you knew its name or not. It is a free, community-maintained format defined at keepachangelog.com: an easy-to-read changelog file with a fixed structure, intended for humans first and machines second. Here is what the spec says, what it gets right, and where it stops if you are running a product with customers.

What the spec actually says

The Keep a Changelog format has four load-bearing rules:

1. Every change goes in the changelog. It is the record of what changed, not a highlights reel.
2. Group by release. Each entry is one release: the version number (typically SemVer) and the date in ISO 8601 (YYYY-MM-DD).
3. Use consistent categories. The standard sections are Added, Changed, Deprecated, Removed, Fixed, and Security.
4. Keep an Unreleased section at the top. Pending changes accumulate under ## [Unreleased] and get a version and a date when you ship.

The spec also aims to keep entries easy to parse, which is why most generators target it. A minimal file looks like:

# Changelog

All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to
Semantic Versioning.

## [Unreleased]

## [1.1.0] - 2026-08-20
### Added
- CSV export for reports.
### Fixed
- Timezone handling in scheduled exports.

Why the format works

• One reader, zero ambiguity. The structure is simple enough that a new contributor knows where a line goes without a wiki page.
• Machine-friendly without being a machine format. Headings, bullets, dates — parsers exist, but a human can read the file directly.
• Git-native. It lives in the repo next to the code it describes; the history is in version control for free.
• Deprecation is first-class. Having Deprecated as a standard section is a small thing with a large effect: teams that use it remove features on a schedule instead of by accident.

Where it stops for a product changelog

The spec was written for projects whose reader is a fellow developer. For a SaaS product with customers, four gaps appear:

• One audience. There is no concept of a customer-facing version versus a developer version of the same release.
• Discoverability. A CHANGELOG.md in a repo is visible to people who already have the repo — not to the customer who never clones it.
• No distribution. No feed, no email, no page. The format says nothing about delivery.
• Maintenance is still manual. The format organizes the file; it does not write it, which is exactly where changelogs go stale (see why changelogs get outdated).

None of these are spec failures — they are scope. The spec answers "what should the file look like"; it does not answer "how does my customer find out."

Tools that implement the spec

Most changelog generators target the Keep a Changelog format, so the spec is the common denominator:

• git-cliff — a free Rust CLI that renders CHANGELOG.md from git history, configurable to emit the standard sections; one of the most popular pure generators.
• release-drafter — a GitHub Action that drafts release notes from pull request labels; output can follow the format.
• standard-version — pairs conventional commits with changelog generation and version bumping in one CLI.
• Hosted services — changelog SaaS tools typically accept the format for imports and keep published entries in the same shape.

The practical move: adopt the spec for the in-repo file (whatever generates it), and choose a delivery layer — hosted page, RSS, email — for the audience the file alone cannot reach. If your generation source is conventional commits, the conventional commits how-to walks the pipeline end to end.

ShipChangelog

ShipChangelog keeps the spec's shape for the content — dated, versioned entries with Added/Changed/Fixed sections — and adds the layer the spec does not cover: a hosted page your customers can find, RSS, an email digest, breaking-change flags, and three audience versions of each release. Free for one repo with 5 entries a month.

FAQ

Should a private, non-OSS SaaS use Keep a Changelog?

For the in-repo file, yes — it is the clearest common format, and future parsers and generators will expect it. For what customers read, treat the spec as the content format and add a delivery layer on top.

Do I need to follow the spec perfectly?

No. Treat it as a lightweight convention: consistency matters more than strict compliance. Pick your category set and date format, then do not improvise per entry.

Is "Keep a Changelog" the same as CHANGELOG.md?

Keep a Changelog is the format; CHANGELOG.md is the filename convention the format assumes. You can use the format in any file, but the standard name is what tooling looks for.

ShipChangelog writes these changelogs for you — start free with 1 repo.