Fifteen changelog entries, ranked by what a reader can tell from them

Fifteen changelog examples sit further down this page, ranked by what a reader can tell from each one. Most advice about changelogs is about tone, and almost none of it is about the thing that decides whether an entry works, which is that hardly anybody reads the whole of one.

That can be stated exactly, not waved at, because the code that cuts them is in this repository.

In this product, the strip that announces the newest release takes the body you wrote, strips every piece of formatting out of it, and cuts it at 120 characters on the last space past the halfway mark, then adds three dots. That's a line in a file, not a design opinion.

So the entry isn't really the artefact. The first sentence is the artefact, and everything after it exists for the smaller number of people who click through.

The fifteen entries below were written for this post, not lifted off anybody's site. They're ranked by one test. Can a person who asked for a thing tell from the entry that it shipped, and can a person who didn't ask tell whether it matters to them.

What is actually inside a changelog entry?

Less than you would think, and knowing the parts is what makes the ranking below obvious, not a matter of taste.

An entry on our side is a release, and a release carries a name, a published date, a body written in Markdown, a flag that pins it to the top of the page, and a list of the things that went into it.

That list is the interesting part, because you don't type it. It's the cards on your board that reached the shipped column, in the order you put them in. Each one arrives carrying its own heading, the category somebody filed it under, and the number of people who voted for it.

The categories are fixed, not free text, and there are five of them. New, improvement, fix, security and breaking change. Fixed categories are worth more than they look.

A reader scanning a year of entries can see at a glance how much of the year was repair and how much was new work, and the first time somebody types Bugfix instead of Bug Fix that ability is gone for good. How ours are wired to the board is written up here.

The vote count travelling with the entry is the part almost nothing else in this category does. It means an entry can say that forty seven people asked for this, without anybody counting anything, because the number was already attached to the request when it shipped.

There's a board doing this already if you want to look at one, and the demo is open without an account.

The fifteen, ranked

Best at the top. Each of these is one entry, as a reader would meet it.

	The entry	What it does	What it costs you
1	Saved views now survive a browser restart. Before this, closing the tab lost them.	Names the change and the old behaviour, so anybody who was bitten by it recognises the moment instantly	Two sentences instead of one
2	You can now export the voter list as CSV, with what each voter pays in a column.	Names the change and then the one detail that decides whether it is useful to you	Nothing. This is the shape to copy
3	Fixed. Votes cast on a custom board were not counting toward the weighted total. They are now, and existing boards were recounted.	Says which case broke, and answers the question every fix raises, which is what happened to the data already affected	Requires you to know the answer before you publish
4	Breaking. The v2 API stops answering on 1 March. Everything it does is in v3 and the routes are the same shape.	Leads with the word that decides whether the reader keeps reading, then removes the fear in the next clause	Nothing, and burying this is the most expensive mistake on the list
5	Search now matches the text of a request as well as its title.	Small, precise, no adjectives. A reader knows in four seconds whether it changes their day	Nothing
6	Two of the four things you voted for this quarter are in this release.	Written to one reader rather than to everybody, which is the only kind of announcement people open twice	Only possible if you know who voted, which most changelog tools do not
7	Nothing shipped this fortnight. The team spent it on the migration that stops the board timing out on large accounts.	An honest empty entry that still tells the reader something, and buys credit for every entry after it	Nerve
8	Dark mode.	Works because the noun is the entire change and every reader already knows what it means	Almost nothing else qualifies, and treating this as a style is how you get number ten
9	New. Dark mode. Improved. Search. Fixed. Export.	Scans quickly and files everything in the right place	The categories are doing all the work and there is no content under any of them
10	Improved the onboarding flow.	Tells the team what happened	Onboarding flow is your word, not the reader's, and nobody outside can tell what changed
11	Comments are faster.	Reads as good news	Unverifiable, so it is forgettable. A number here would have made it the best entry on the list
12	v2.4.0	Correct	A version number is an address, not an announcement. Nobody has ever wanted one on its own
13	Refactored the vote aggregation into a single query.	True	An engineering note in a customer facing place. The reader learns that something they cannot see is different
14	This release includes 47 commits from 6 contributors.	Sounds like a lot of work	Measures effort rather than value. The reader does not buy your effort
15	We have been hard at work on some exciting improvements and cannot wait for you to try them.	Nothing	Every word is about you, and the reader learns not to open the next one

The line falls between eight and nine, and it's not about quality of writing. Everything above the line names a specific change in the reader's vocabulary. Everything below it names a category, a version, an internal system or a feeling.

Three of the top entries do the same trick, which is worth saying out loud because it's the cheapest improvement available to anybody. They state the old behaviour as well as the new one.

Search now matches the text as well as the title tells you what it used to do. Saved views now survive a browser restart tells you they used not to. A reader can't judge a change without knowing what it replaced, and one extra clause supplies it.

The bottom of the list has a pattern too. Entries thirteen and fourteen were both written by somebody proud of the work, and pride is exactly the wrong instinct here.

Nobody outside your company can see a refactor and nobody is impressed by a commit count. If you need somewhere to be proud, an engineering blog is the right place and a changelog isn't.

Why does the first line carry the whole entry?

Because almost every surface a release appears on truncates it, and ours truncates it at 120 characters.

That number is ours, not a law of nature, but the shape of it's not. Every in product strip, every notification tray and every email preview line does some version of the same thing. If your first sentence is a preamble, the truncated version of your release is a preamble and nothing else.

There's a second reason, and it's the one people get wrong. The reader has a specific question, which is whether the thing they asked for six weeks ago is in this release. They're not reading.

They're scanning for one noun. Put the noun in the first four words and they find it. Open with a paragraph about how much the team has been shipping lately and they won't.

The practical rule that falls out of that is to write the entry, then delete the first sentence, then check whether anything was lost. Nine times in ten the first sentence was throat clearing and the entry is better without it.

What gets sent, and what stays on the page

The message and the page carry different text, and the difference isn't a setting you can find.

When you publish a release on our side, the message that goes out isn't built from the body you wrote. It's built from the headings of the cards in the release.

Your voters get their own items in bold, and everything else in the release arrives as one small line underneath saying also in it. The body, the part you spent time on, stays on the page for whoever clicks.

The consequence is worth taking seriously. The heading you typed on a card months ago, in a hurry, probably before you had thought about it, is the release note.

Not the thing you carefully wrote on publishing day. If you take one habit from this post, it's to fix the headings before you publish rather than after, because the headings are the announcement.

It also means the same release produces a different message for every person who gets one, because the split between your items and the rest is different for each of them.

Nobody gets a mail merge with their name in it. They get a list that's genuinely about them, which is a different thing and works far better.

One thing we deliberately don't do. Fixing a typo in a published release doesn't send a second announcement. The moment the first message goes out is stamped on the release, and a republish checks that stamp before it sends anything.

That matters more than it sounds, because a team that's frightened of correcting a published entry ends up with a changelog full of mistakes nobody dares touch.

How do you keep a changelog in a Markdown file?

If you're not using a tool yet, a single file in the repository is the right first version, and it's better than most tools because it lives where the work happens.

The convention that survives contact with a real team is one file, newest at the top, one heading per release, and the five categories as sub headings underneath. Nothing else. No table of contents, no badges, no links to issue numbers that will outlive the issue tracker.

# Changelog

## Unreleased

### Fixed
- Votes cast on a custom board were not counting toward the weighted total.

## 29 April 2026

### New
- Export the voter list as CSV, with what each voter pays in a column.

### Improved
- Search matches the text of a request as well as its title.

### Fixed
- Saved views now survive a browser restart. Before this, closing the tab lost them.

### Breaking
- The v2 API stops answering on 1 March. Everything it does is in v3.

The Unreleased heading at the top is the part that makes the habit stick. Anybody who ships something adds a line to it in the same commit, and publishing a release is then a matter of renaming a heading rather than remembering a fortnight.

Two things about that file worth knowing before you paste it anywhere. It's a document for people, so write dates in a form a person reads, not a form a machine sorts.

And keep issue numbers out of the lines themselves, because a changelog outlives the tracker it was written against far more often than anybody expects.

If you later move that file into a tool, here's what to expect, measured against ours, not guessed. Our release bodies are rendered as plain CommonMark with no extensions, and the difference bites in five specific places.

What you write	What the release body does with it
A heading, a list, a link, bold text or inline code	Renders as you would expect
A Markdown table	Does not render. The pipes come out as literal text in one paragraph
Strikethrough with two tildes	Does not render. The tildes stay on the page
A bare web address on its own	Does not become a link. Write it as a Markdown link instead
A task list with square brackets	Renders as a list with the brackets still visible in it
Raw HTML of any kind	Is dropped and replaced with an HTML comment

That's not a complaint about the library, it's the CommonMark default doing exactly what it says. It matters because the two habits people carry in from a code host, tables and task lists, are the two that quietly break.

There's a generator on this site in the same five categories if you would rather type into boxes, and the template as a file is here.

What format should a changelog entry follow, and what do the examples above share?

A version number or a date as the heading, one line of summary under it, and the changes grouped under category labels that never change wording.

That's the shape every example above follows. The widely used convention for a file kept in the repository says the same thing in more words, being that the newest release sits at the top, that work which has landed but not shipped sits under an Unreleased heading, and that changes are grouped, not listed flat. The Markdown section above writes one out in full.

An app changelog is the same object inside a smaller box. A store listing shows a few lines before it truncates and an in product panel usually shows one, so the format survives but the first line has to carry the whole entry on its own.

What that looks like written out for a store listing and for the panel is on its own page.

The label wording is the part worth being strict about. The first time somebody files a fix under Bugfix instead of Fix, the ability to scan a year of entries and see how much of it was repair is gone, and no tool gives it back.

What does it cost to keep one going?

More than anybody admits, and the honest number isn't a price.

Ours has one release on it, dated 29 April 2026, and we have shipped a great deal since. The work went out without the cards moving to the shipped column on the public board first, which is precisely the discipline this post is recommending to you.

The page is still there, unedited, because a changelog that only looks good when the team is on form isn't a changelog.

That's the real argument for building one out of the board rather than as a separate document. A separate document can be kept tidy by whoever is tidy. One built from the board only moves when the board moves, so when it goes quiet the reason is visible instead of hidden.

The failure mode to watch for isn't laziness. It's that the changelog becomes a second job with its own weekly slot, at which point it competes with shipping and loses. Every convention in this post is chosen to make the entry a byproduct of work that was happening anyway.

Which part does a tool actually help with?

Two parts, and it's worth being clear that they're the boring two.

The first is the list. If your entries are already cards that somebody moved to a shipped column, the tool assembles the release for you and you write only the paragraph at the top. That removes the step where somebody sits down with a git log and tries to remember what mattered.

The second is delivery, which is the part almost every list of changelog tools gets wrong. Publishing a page isn't telling anybody.

We checked ten tools in this category on their own sites on one day for whether they deliver by email at all, and seven of them say on their own pages that they do.

Ours emails the people whose own vote is in the release and stops there, which is a deliberately small list, not a broadcast.

What a tool doesn't help with is the writing, which is the part this whole post is about. No tool will turn entry fifteen into entry two.

If you're still working out what a changelog owes a reader that release notes don't, that question has its own page, and the answer changes what you write.

14 days, a card at signup, then $9 or $39 a month.