Most teams know they should keep a changelog and still skip it, because the blank page is the hard part. Here is the short version of what I have learned, with examples you can copy.

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.

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

Six habits of a useful changelog: write for the reader, group changes by type, newest first with a date, call out breaking changes, link to the detail, leave out the noise

  1. Write for the reader, not the codebase. "Export any report to PDF" tells a user what they can do. "Add PDF exporter service" tells them nothing.
  2. Group changes by type. Headings such as Added, Changed, Fixed, Removed and Security let readers jump to what they care about.
  3. Put the newest version first, with a date. Use the ISO format YYYY-MM-DD so it reads the same in every country.
  4. Call out breaking changes and say what to do. Put them near the top of the entry. If you follow semantic versioning, a breaking change is also your signal to bump the major version.
  5. Link to the detail. One line per change, with the pull request or issue for readers who want depth.
  6. Leave out the noise. Skip dependency bumps, refactors and typo fixes unless they change behaviour for users.

Before and after

Six commits from a release, 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 

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) 

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.

Three changelog examples you can copy

These use an invented app called Acme.

1. A user-facing entry

## 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. 

2. A developer entry with a breaking change

## [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) 

3. A security fix

## [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. 

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

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?

Making it a habit

Two approaches work well. Keep an Unreleased section and add a line with every merged pull request, so the work is spread across the release. Or draft the entry at release time from the list of merged changes, then edit it by hand.

I am building ReleaseTale, an AI changelog and release notes generator for GitHub, to take the drafting step off your plate (it is pre-launch and has a waitlist). Either way, the part that keeps a changelog accurate is a human reading it before it goes out.

If you want the longer version, with the full structure and more detail on each habit, it is on the original post: How to write a changelog (with examples). For the file format itself, see the Keep a Changelog template.

What does your team do to keep the changelog from slipping? I would like to hear.