Changelog examples
worth copying.

Good changelog examples share three things: a title that states the change, a sentence on what the user can now do, and an honest note on what to do next. Below are four entries, one for each kind of change, followed by changelog vs release notes and a checklist.

Start free See the demo board

Four changelog examples, by category

Each changelog example below is written for a fictional product, in the four categories Kjerr's Announcements section uses. Copy the shape, not the words.

New feature

Two-factor authentication is here

You can now protect your account with a second step at sign-in. Open Settings, then Security, scan the QR code with any authenticator app and save your recovery codes. Workspace owners can require it for every member. This was one of the most requested ideas on our board.

Why it works: Leads with what the user can now do, says where to find it, and credits the request.

Improvement

Reports load up to three times faster

We rebuilt how reports are calculated. The monthly summary that took six seconds on large accounts now opens in under two, and date ranges longer than a year no longer time out. Nothing changes in the numbers themselves.

Why it works: Gives a number the reader can feel, and answers the worry that the data changed.

Fix

Fixed: CSV exports dropped the last row

Exports with more than 10,000 rows were missing their final row. That is fixed, and exports made from today are complete. If you exported a large report in the first half of August, run it again.

Why it works: Says what was wrong, who was affected and what they should do. No euphemism.

Announcement

What we are building this autumn

A short look at the next few months, based on what you voted for. Slack notifications are in development now. Dark mode is next; it is the most voted idea on the board and design has started. We will post here when each one ships.

Why it works: Sets expectations without dates it cannot keep, and points back to the votes.

Anatomy of a changelog example that works

  1. Title: the change, not the version. “Reports load up to three times faster” tells a reader whether to care. “v4.12.1” does not.
  2. Category. New feature, improvement, fix or announcement. It lets people skim and filter.
  3. What you can now do. One or two sentences from the user's side of the screen.
  4. Where to find it. The menu path, or a link.
  5. What to do next. Often nothing. When a fix needs a re-export or a setting, say so plainly.
  6. Credit the request. If users asked for it, link the request. It is the cheapest proof that feedback is read, and the first step in closing the customer feedback loop.

Changelog vs release notes

A changelog is the running record of every notable change; release notes are the write-up of one release. The changelog is a list you scan: short entries, newest first, one per change. Release notes are a document you read: they group the changes in a version, explain the larger ones with screenshots and carry upgrade or migration steps.

Small teams usually need only the changelog, with a longer entry when a release deserves it. Products with versioned installs or an API tend to publish release notes as well, and link each changelog entry to them.

A checklist before you publish

Read the entry as a user who has never seen your public product roadmap.

  • Does the title make sense without the body?
  • Is the first sentence about the user, not the team?
  • Is there a number, a path or a screenshot where one would help?
  • If something broke, does it say who was affected and what to do?
  • Are the requests it answers linked?
  • Will the people who asked be told, not only the people who happen to visit?

Publishing these in Kjerr

Kjerr's Announcements section is a changelog tool with the four categories above. Posts take headings, lists, links and images, reference the ideas they answer, and can email subscribers on publish.

  • Categories, search by text and date, emoji reactions and comments.
  • A verified email subscription for readers.
  • Linked ideas appear under the post; setting them to Shipped emails their voters.
  • A widget for your own site shows the same announcements in a side panel, with the unread count on the launcher.

Questions, answered plainly.

What is a changelog?

A changelog is a dated, reverse-chronological list of what changed in a product, written for the people who use it. Each entry says what changed, who it affects and what, if anything, they need to do.

What is the difference between a changelog and release notes?

A changelog is the running record of every notable change; release notes are the write-up of one release. A changelog entry is a few sentences. Release notes can run to a page, with screenshots and upgrade steps. Many products publish both in one place.

What should a changelog entry include?

A title that states the change, a category, one or two sentences on what the user can now do, where to find it, and any action needed. If the change answers a request, say so and link it.

How often should a changelog be updated?

Whenever something users can notice ships. A short entry every week or two builds more trust than a long one every quarter.

Where should a changelog live?

On a public page with its own address, so it can be linked, searched and indexed, and by email for people who subscribe. Kjerr puts it on the same board as the feature requests.

Related pages

Changelog toolKjerr's changelog, in detail.
Public roadmap toolWhat is coming, before it reaches the changelog.
The customer feedback loopWhy the announcement closes the loop.

Give your users an answer.

Kjerr is free during early access, with every feature included and no credit card. When paid plans arrive they will be priced per workspace, never per admin seat and never per tracked user, so the number of people who post, vote or comment never changes the bill.

Start your changelog See the demo board