Blog

How to write a changelog (with examples)

A changelog is a dated, per-version list of what changed in your software, written so the people who use it can tell what is different. To write a good one, group changes by type, describe the effect on the reader instead of the code, put the newest version first, and flag anything that breaks existing behaviour.

Most teams know they should keep one and still skip it, because the blank page is the hard part. This guide gives you a structure to fill in, six habits that make entries worth reading, and a before and after example you can copy.

Who reads a changelog

Before you write a line, decide who the entry is for. A changelog usually has four kinds of readers:

  • Users who want to know whether a bug they hit is fixed or a feature they asked for exists.
  • Developers who integrate with you and need to know what could break their code.
  • Support and sales who answer "when did this change?" and need a date.
  • Your future self, trying to remember why behaviour changed three versions ago.

If your audience is mostly end users, keep entries short and free of internal terms. If it is mostly developers, include identifiers and links. Our guide on changelogs versus release notes explains when to write both.

Why a commit log is not a changelog

It is tempting to paste the output of git log and call it done. Commit messages are written for maintainers, in the moment, and they describe how the code changed rather than what changed for the reader. They also include work nobody outside the team cares about: dependency bumps, refactors and typo fixes.

The Keep a Changelog guide makes the same point: using commit log diffs as changelogs is a bad idea because they are full of noise.

A changelog is an editorial product. Someone has to decide which changes matter, group them, and say them in plain language. That judgement is the whole job.

Six habits of a useful changelog

1. Write for the reader, not the codebase

Describe the effect, not the implementation. "Export any report to PDF" tells a user what they can do. "Add PDF exporter service" tells them nothing.

2. Group changes by type

Readers scan for what they care about. Headings such as Added, Changed, Fixed, Removed and Security let them jump straight there. The Keep a Changelog template uses exactly these groups and is a good default.

3. Put the newest version first, with a date

People arrive wanting the latest news. Put the newest release at the top and give every version an unambiguous date, ideally in the ISO format YYYY-MM-DD, so it reads the same in every country.

4. Call out breaking changes and say what to do

A removed option or a renamed setting deserves its own line near the top of the entry. Say what changed and what the reader should do about it. If you follow semantic versioning, a breaking change is also your signal to increase the major version.

5. Link to the detail

Keep each entry to one line and link the pull request or issue for readers who want depth. That keeps the changelog scannable without hiding the evidence.

6. Leave out the noise

Dependency bumps, internal refactors, formatting changes and test-only commits rarely belong. The exception is a dependency update that fixes a security problem or changes behaviour for users.

Before and after: from commits to a changelog entry

Here are six commits from a release, exactly as they appear in the log:

a3f9c21 feat: add pdf export (#142)
7be04d8 fix: oauth redirect loop (#139)
51c2e90 chore: bump deps
e8d1b37 feat: export button in toolbar
0f6a4c2 fix: typo in settings
92b7d15 refactor: report service

Two of them are features and one is a bug fix that users will notice. The rest are maintenance. Written for the reader, the entry becomes:

## 1.2.0 - 2026-10-12

### Added
- Export any report to PDF from the toolbar (#142)

### Fixed
- Signing in no longer sends you back to the login page in a loop (#139)

Notice what happened. The two feature commits merged into one line, because the toolbar button is part of the same capability. The typo, the refactor and the dependency bump disappeared. The bug fix lost its jargon. You can see more finished examples of both user-facing and developer-facing entries on our examples page.

git loga3f9c21feat: add pdf export7be04d8fix: oauth redirect loop51c2e90chore: bump depse8d1b37feat: export button0f6a4c2fix: typo in settings92b7d15refactor: report service✦CHANGELOG.md## 1.2.0 - 2026-10-12### Added- Export reports to PDF### Fixed- Login redirect loop3 of 6 commits left out
A changelog keeps what readers can notice and drops the noise.

Changelog examples you can copy

The same release can be written for different readers. These three short changelog examples use an invented app called Acme to show the pattern. Copy the structure and replace the details with your own.

Example 1: a user-facing changelog entry

For customers. Plain words, the benefit first, no ticket numbers or code names.

## What's new in Acme 3.4 (October 12, 2026)

New
- Export any report as a PDF from the toolbar.
- Dark mode now follows your system setting.

Improved
- Large reports open faster.

Fixed
- Signing in no longer sends you back to the login page.

Example 2: a developer changelog entry with a breaking change

For people who integrate with your project. It follows the Keep a Changelog format, puts the breaking change first and says what to do about it.

## [4.0.0] - 2026-10-12

### Changed
- **Breaking:** `createClient()` now requires an `apiKey` option. Pass the key you previously read
  from the `ACME_KEY` environment variable. (#201)

### Added
- `client.reports.export("pdf")` returns a PDF as a `Buffer`. (#142)

### Fixed
- Retries no longer repeat a request that already succeeded. (#188)

Example 3: a security fix entry

State who was affected, which versions, and what to do. Do not publish exploit details before users have had a chance to update.

## [3.3.2] - 2026-09-30

### Security
- Fixed an issue where an expired invite link could still be used to join a workspace.
  Affects versions 3.0.0 to 3.3.1. Update to 3.3.2; no other action is needed.

What the three examples share: a version and a date, changes grouped by type, one line per change written from the reader's point of view, and a clear instruction wherever the reader has to act. For the full file layout and the six change types, see the Keep a Changelog template. To decide which of these two styles you need, read changelog vs release notes.

A checklist before you publish

  • Is every entry a change the reader could notice or must act on?
  • Is the version number and the date correct?
  • Are breaking changes at the top, with what to do about them?
  • Does each line read without knowing the codebase?
  • Does each important line link to its pull request or issue?
  • Could someone find the changelog without asking you where it is?

Where to publish it

You can publish the same content in more than one place:

  • A file in the repository, usually CHANGELOG.md, which suits developers and open source projects.
  • A public page on your website, which suits customers and is easy to share and search.
  • Inside the product, as a short "What's new" notice, which reaches people while they are using it.

Making it a habit

The best changelog process is the one your team will actually follow. Two approaches work well. You can keep an Unreleased section and add a line with every merged pull request, so the work is spread across the release. Or you can draft the entry at release time from the list of merged changes, then edit it by hand.

If the drafting step is what slows you down, a tool can help. ReleaseTale reads the commit messages, pull request titles and descriptions, and file names for the commits you pick, then writes a first draft in two versions. You still review and edit it before you save, which is the part that keeps it accurate.

Frequently asked questions

What should a changelog include?

Each release needs a version number, a date and a short list of changes grouped by type, such as Added, Changed, Fixed and Removed. Write every entry from the reader's point of view and link to the pull request or issue when more detail helps.

How often should you update a changelog?

Update it with every release, and keep an Unreleased section at the top for changes that have merged but not shipped. Adding entries as you merge is easier than reconstructing them from git history later.

Should a changelog be written for developers or users?

Decide per audience. A developer changelog lists every notable change per version, while user-facing release notes explain only what matters to customers. Many teams keep both.

What does a good changelog example look like?

A good changelog entry has a version and a date, groups changes under headings such as Added, Changed, Fixed and Security, and describes each change from the reader's point of view. This guide includes three copyable examples: a user-facing entry, a developer entry with a breaking change, and a security fix.

Related articles