The changelog format, without the ceremony

Definition

What a changelog is

A changelog is a dated, reverse-chronological list of the notable changes in each version of a piece of software, written for the people who use it. That last clause is the whole game. Your git log is also a chronological list of changes, and it is not a changelog, because it was written for you.

In a repo it is conventionally a CHANGELOG.md at the root. For a product it is usually a page, like the updates page on this site. Same idea, different wrapper.

Conventions

The standard format

The shape most of the ecosystem settled on is Keep a Changelog: newest version first, each version a heading with a date, changes grouped under a small fixed set of categories. Added, Changed, Deprecated, Removed, Fixed, Security. Versions follow semver when the thing being versioned is software other software depends on.

# Changelog

## [Unreleased]
### Added
- Lines accumulate here as PRs merge.

## [2.1.0] - 2026-08-14
### Added
- CSV export on the reports screen.
### Changed
- Session timeout raised from 30 to 60 minutes.
### Fixed
- Dates no longer shift by a day in UTC+13.

## [2.0.1] - 2026-07-30
### Fixed
- Crash on empty search results.

The Unreleased section at the top is where lines land as work merges, then get promoted to a version heading at release time. It turns the changelog from a pre-release panic into a habit. My opinion, but held firmly: this one convention is worth more than all the others combined.

You do not need all six categories. A one-person project does fine with Added, Changed and Fixed. Use the empty ones never; delete them.

The distinction

Changelog vs release notes

Same facts, different job. A changelog is a record: complete-ish, terse, organized for someone scanning history to answer “when did this change”. Release notes are an announcement: selective, written in sentences, organized to tell the people affected by one release what they got. The changelog is a ledger, release notes are a letter.

In practice small teams publish one artifact that does both jobs, and that’s fine. It only matters that you know which job a given entry is doing. If you want the letter version, the release notes template is that.

The craft

Writing the entries

An entry is one line, and the line describes what changed from the user’s side of the glass. “Fixed: exports no longer time out on large accounts” is an entry. “Refactored export batching” is a commit message that wandered into the wrong file.

Tooling can get you partway. Conventional commits and generators will assemble a categorized list from your history, and machine-drafted entries are genuinely fine raw material. What they produce is still written from the diff’s point of view, so somebody has to translate it before it is a changelog. I speak from a very specific position here: Merge & Tell drafts my entries from each merged PR, and I still read and edit every one before it publishes, daily. The draft is the easy 80 percent. The edit is where it stops sounding like a robot did it.

Kept short on purpose

The practices that matter

• Newest first. Nobody scrolls to the bottom for the current version.
• A real date on every version, in a format that sorts.
• One change per line, one line per change.
• Group by category, not by who did the work.
• Call out breaking changes louder than anything else in the release.
• Publish on merge or on release, not in quarterly batches from memory.

Restraint

What to leave out

Dependency bumps nobody is affected by. Internal ticket numbers that resolve for you and 404 for everyone else. “Miscellaneous fixes and improvements”, which is the sound of a changelog giving up. And anything secret, because a changelog is the most-read page you will ever publish about your own product, a lesson I keep relearning from the analytics.

A short honest changelog beats a long padded one. If a release changed two things, the entry has two lines, and that is a perfectly good entry.