Changelog Template, Format and Examples

The short answer

A changelog lists every notable change to your product, newest version first, with a date on each release and changes grouped by type: Added, Changed, Deprecated, Removed, Fixed, and Security. Copy the template below to start one in 30 seconds.

Need the definition first? Read what is a changelog

Changelog template

This template follows the Keep a Changelog format, the most common convention for CHANGELOG.md files. Replace the versions, dates, and entries with your own.

# Changelog

All notable changes to this project are documented in this file.

The format is based on Keep a Changelog (https://keepachangelog.com/en/1.1.0/),
and this project adheres to Semantic Versioning (https://semver.org/).

## [Unreleased]

### Added
- [New capability, one line per change]

## [2.4.0] - 2026-09-15

### Added
- Invoice approvals: reviewers can approve, reject, or request changes (#1452)

### Changed
- CSV exports now include the invoice currency column (#1438)

### Deprecated
- The v1 invoices endpoint. It will be removed in 3.0.0; use v2 instead (#1447)

### Fixed
- Long invoices no longer overlap the PDF footer (#1440)

### Security
- Upgraded the PDF renderer to patch a file-parsing vulnerability (#1444)

## [2.3.1] - 2026-08-28

### Fixed
- Date filters now respect your workspace time zone (#1419)

[Unreleased]: https://github.com/your-org/your-repo/compare/v2.4.0...HEAD
[2.4.0]: https://github.com/your-org/your-repo/compare/v2.3.1...v2.4.0
[2.3.1]: https://github.com/your-org/your-repo/compare/v2.3.0...v2.3.1

Customer-facing changelog template

A public product changelog has a different reader: customers, not contributors. Drop the version-compare links, lead each entry with what the reader can now do, and use labels customers recognize.

## September 15, 2026

New
- Approve invoices without leaving billing. Reviewers can approve, reject, or request changes on any invoice.

Improved
- CSV exports now include each invoice's currency.

Fixed
- Long invoices no longer overlap the PDF footer.

Heads up
- The v1 invoices API retires on March 31, 2027. See the migration guide.

Changelog format, section by section

Group each release's changes under these six headings, and skip any heading with nothing in it.

Three more conventions round it out. Put the newest version first. Date every release as YYYY-MM-DD, so nobody wonders whether 03/04 means March or April. And keep an Unreleased section at the top so changes collect as they merge.

Source: Keep a Changelog 1.1.0

How to write a changelog

Keep an Unreleased section

Add each entry when the change merges, not on release day. When you ship, rename Unreleased to the new version and date, then start a fresh Unreleased section.

Log notable changes, not every commit

A changelog is for the people using your software. Refactors, invisible dependency bumps, and CI tweaks don't belong. If a user or integrator wouldn't notice it, leave it out.

Write for the reader

Describe the effect, not the implementation. "Exports no longer time out on large workspaces" beats "Optimize export query batching."

Link the issue or pull request

End each entry with its issue or PR number, so anyone who needs the detail can find it in one click.

Never paste the git log

Commit messages are written for other engineers in the moment. Dumping them into a changelog buries the changes that matter under dozens that don't.

Call out breaking changes

Anything that needs action goes under Deprecated or Removed, with the version it takes effect in and what to use instead.

How much notice to give before removing something: how to communicate breaking changes and deprecations

Changelog examples worth studying

These public changelogs each do one thing especially well.

Want more? Browse release notes examples from product teams

Generating a changelog automatically

If your team writes commit messages in the Conventional Commits format (feat:, fix:, and so on), release tooling can draft changelog entries for you. That's a solid starting point for a developer changelog.

Treat the output as a draft, though. Commit messages describe what an engineer did, not what a user gets, so someone still needs to cut the noise and rewrite entries for readers.

More on automating without losing quality: how to automate release notes

Frequently asked questions

What's the difference between a changelog and release notes?

A changelog is the complete, technical record of changes, usually written for developers. Release notes are the curated, reader-friendly story of what changed and why it matters, and they're usually drawn from the changelog.

Full comparison: release notes vs. changelog

Should a changelog include every commit?

No. Include every notable change a user or integrator would notice, grouped by type. Leave out refactors, internal tooling, and dependency updates nobody can see.

Should a changelog be a CHANGELOG.md file or a public page?

Both have a place. A CHANGELOG.md in your repository serves developers and open-source users. A public changelog page serves customers, who shouldn't need a GitHub account to see what changed.

What is Keep a Changelog?

It's a widely used convention for formatting changelogs, created by Olivier Lacan. It groups changes under Added, Changed, Deprecated, Removed, Fixed, and Security, lists the newest version first, and dates every release.

Should the newest changes go first?

Yes. Readers almost always want the latest release, so reverse chronological order saves them scrolling. Keep a Changelog recommends it too.

Publish a changelog customers can find

LaunchNotes gives you a hosted changelog customers can browse and subscribe to, plus an in-app widget and email updates, all from one post.

See how it works: the LaunchNotes changelog