Every software project changes. The question is whether your users find out about those changes from you — clearly, in one place — or from a broken workflow and an angry support email. A changelog is how you make sure it’s the first one. This guide covers the standard format used by thousands of projects, how to write entries people can actually use, and the mistakes that turn changelogs into noise.

If your project doesn’t have its basic documentation in order yet, start with our guide to writing a README file developers actually read — the changelog builds on it.

What a changelog is (and is not)

A changelog is a curated, human-written record of the notable changes in each version of a project, newest first. Three words in that definition do the heavy lifting:

• Curated — someone chose what matters. A changelog is not an automatic dump of every commit.
• Human-written — entries describe what changed in terms of what users can now do (or must stop doing), not in terms of internal code.
• Per version — changes are grouped under a version number and a date, so a reader can answer “what changed between the version I have and the version I want?”

A changelog is not release notes (those are marketing for one release) and it is not a git log (that is a raw record for developers). It sits between them: complete like a log, readable like notes.

The standard format

The widely adopted convention comes from the Keep a Changelog project, and it is simple enough to copy today:

1. A file named CHANGELOG.md in your repository root.
2. An [Unreleased] section at the top, where changes accumulate between releases.
3. One section per release, headed with the version and date: ## [1.4.0] - 2026-10-15.
4. Inside each release, changes grouped under a fixed set of categories: Added, Changed, Deprecated, Removed, Fixed, and Security.

Those six categories cover everything a user needs to know. Added is new capability. Changed is existing behavior that now works differently. Deprecated still works but is scheduled for removal — say so early, while users can still migrate. Removed is gone, and it is the section users search first after an upgrade breaks something. Fixed is bug repairs. Security is vulnerabilities and their fixes, and it deserves its own heading even when it overlaps with Fixed, because it is the section cautious users scan before upgrading.

A copy-paste template

# 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

### Changed

## [1.4.0] - 2026-10-15

### Added
- Export reports as CSV from the Reports page.

### Fixed
- Correct totals on invoices with more than 50 line items.

## [1.3.2] - 2026-09-28

### Security
- Update session handling to close a token-reuse issue.
  Users on older versions should upgrade.

When you cut a release, rename the Unreleased section to the new version and date, and start a fresh empty Unreleased above it. That two-minute habit is the entire maintenance routine.

Pair it with Semantic Versioning

A changelog answers “what changed”; a version number should hint at “how much it matters” before anyone reads a word. That is Semantic Versioning (SemVer): MAJOR.MINOR.PATCH.

• PATCH (1.4.0 → 1.4.1): bug fixes only. Safe to upgrade without reading.
• MINOR (1.4.1 → 1.5.0): new features, backward compatible. Worth a skim.
• MAJOR (1.5.0 → 2.0.0): breaking changes. Read the changelog carefully, especially Removed and Changed, before upgrading.

When version numbers follow SemVer, your changelog and your versions tell the same story, and users learn to trust both.

How to write entries people can use

Write for the user, not the codebase. “Fixed null-pointer exception in the billing module” means nothing to the person whose invoice total was wrong. “Fixed incorrect totals on invoices with more than 50 line items” tells that person exactly why the upgrade matters to them.

Lead with a verb, in the past tense. Added, Fixed, Changed, Removed, Improved. Scannable entries start the same way, so readers can skim a column of verbs and stop at the ones that matter.

Name the breaking changes loudly. If an upgrade requires action — a config change, a renamed setting, a migration — say it in the entry itself, not three paragraphs into a linked document. Surprises are what make users afraid to upgrade at all.

Link generously. Reference the issue, pull request or documentation page behind an entry where you can. The changelog stays short; the detail lives one click away for whoever needs it.

One entry per user-visible change. Ten commits that together produce one feature are one entry. One commit that changes two unrelated behaviors is two.

Changelog, release notes, or git log?

Use all three, for different audiences. The git log is the complete raw record, for developers, forever unedited. The changelog is the curated history of every version, for users deciding whether and how to upgrade. Release notes are a per-release announcement — highlights, screenshots, the story of this version — for people who have not decided to upgrade yet. Teams that confuse them usually end up with a git-log dump nobody reads and release notes that quietly omit the breaking change.

Can you automate it?

Partly. Tools can draft changelog entries from pull-request titles and labels, or from conventional commit messages, and on a busy project that drafting step saves real time. But the output still needs a human pass, because automation cannot tell the difference between a commit that changed behavior and one that only refactored internals — and only the first kind belongs in a changelog. Automate the collection; curate the publication.

Five mistakes that kill changelogs

1. Dumping the git log. Commit messages are written for the author, at the moment of the commit. Pasted into a changelog, they bury the two changes users care about under forty they don’t.
2. Skipping versions. A changelog with 1.2.0 followed by 1.5.0 sends every reader hunting for what they missed.
3. Writing entries only developers understand. If a user cannot tell from the entry whether they are affected, the entry failed.
4. Hiding breaking changes. Burying a removal inside Fixed, or not mentioning it at all, is how projects earn a reputation for breaking upgrades — and users who stop upgrading entirely.
5. Letting it rot. A changelog last updated eight releases ago is worse than none: it actively teaches users that your documentation cannot be trusted. Documentation habits compound — the same discipline is behind documentation that improves a project tenfold rather than decorating it.

Frequently asked questions

Where should the changelog live?
In a CHANGELOG.md file in the repository root, where contributors will find it next to the README. Many projects also publish the same content on a releases page — that’s fine, as long as one source is canonical and both are updated together.

How far back should it go?
Start from the next release and keep every version from then on. Backfilling ancient history from the git log is optional and rarely worth it; a short note covering the current major version is enough.

Should every change get an entry?
Every user-visible change, yes. Internal refactors, test changes and build fixes that alter no behavior can stay in the git log.

What’s the difference between Deprecated and Removed?
Deprecated means “still works, will be removed in a future release” — it is a warning with a grace period. Removed means it is gone in this version. Deprecate first, remove later, and record both.

Bottom line

A good changelog is a promise kept in public: every version, what changed, in language the user speaks, with the breaking changes impossible to miss. The format takes ten minutes to set up — a CHANGELOG.md, an Unreleased section, six categories, SemVer numbering — and two minutes per release to maintain. Few documents repay that little effort as reliably.