The short version
- Publish whenever a user would notice something, and at least monthly even when nothing changed.
- Five categories cover almost everything a web product ships.
- One sentence, then a grouped list. Longer than that and nobody finishes it.
- Whether anybody opens the second entry is decided by whether the first was worth the time.
Keeping a changelog is easy. Keeping one anybody reads twice is a different problem, and it comes down to one thing, whether the first entry somebody read contained something they cared about, and whether they could tell in one sentence.
Everything below is downstream of that.
How often should you publish?
Whenever something a user would notice changes, and at least monthly even when nothing did.
Cadence matters more than volume. A changelog with a short entry every two weeks reads as a live product. One with four long entries a year reads as a product that's worked on occasionally, whatever the four entries contain.
The rule that keeps it alive is this. A quiet month gets a two line entry, not silence. Three bugs fixed, written in one line each, takes five minutes and it's the difference between a record and an abandoned page.
There's a changelog to look at, and the demo is open without an account.
Want these published and delivered rather than written and forgotten? Ten changelog tools, checked on their own sites for email, a feed and a widget.
What to group entries by
Five categories cover almost everything a web product ships.
| Category | What goes in it | How often it gets used |
|---|---|---|
| New features | Something that did not exist | Every few releases |
| Improvements | Something that existed and is better | Most releases |
| Bug fixes | Something that was broken | Almost every release |
| Security | Anything a security conscious reader should know | Rarely, and it is read closely when it appears |
| Breaking changes | Anything requiring the reader to act | Rarely, and it is the most consequential |
Anything that fits none of them goes in Other. A release where Other is the longest group is a release that wasn't sorted, and the fix is at write time rather than in the template.
How long should an entry be?
One sentence, then a grouped list. Usually between 100 and 300 words.
The first sentence carries the load because it's the part that survives every surface the entry appears on. On our own side the banner that announces the newest release strips every piece of formatting out of the body and cuts it at 120 characters. Whatever is past that exists for the people who clicked.
The practical consequence is to write the sentence last, after the grouped list, so you know which item is actually the most consequential.
The one thing that decides whether anybody opens the second entry
Whether the first one was worth the time.
A reader who opens a changelog entry and finds nine items about things they don't use and none about the thing they do has spent attention and got nothing. They will skim the next one, and they will stop opening the one after that.
There are two ways to make an entry worth somebody's time, and only one of them scales.
Write better first sentences. Real, limited, and it works.
Tell the specific people who asked. If you know that eleven people asked for the filtering, the entry announcing the filtering is worth opening for exactly those eleven, and it doesn't depend on your prose at all.
The second is the one that changes the numbers, and it's only possible if the requests and the releases are the same system.
Where should it live?
Somewhere with a stable address, reachable without an account, linked from the product.
The link from inside the product is the part most often missing. A changelog nobody can reach from the place they're working is a page for evaluators only.
The mistakes
Batching a quarter into one entry. Everything becomes "various improvements", because nobody remembers.
Writing from the commit log. A reader can't tell which merged branch affected them.
Enthusiasm about small things. If a one line bug fix is announced with the same excitement as a major feature, the reader learns that the tone carries no information.
Announcing nothing for two months and then a redesign. The silence did more damage than the redesign fixed.
No dates. The single most used field in a changelog is the date.
How do you do this without a tool?
A markdown file, newest first, a heading per release with a date, five groups under each, published at a stable address and linked from your product's footer and settings page.
That's a complete changelog. What it can't do is the second half of the entry problem. Nobody who asked for a feature learns from the file that it shipped, so the entry has to earn every reader with prose alone.
How does this product do it?
The items in a release are the cards that reached the completed column of the board, each carrying its heading, the category it was filed under, and the number of people who voted for it.
The generated body groups them into New Features, Improvements, Bug Fixes, Security and Breaking Changes, with Other as the catch all.
A release has a name, a published date, a markdown body you can edit, and a featured flag that pins it to the top of the page.
The people who asked for each item are known, because the vote is attached to a person, which is what makes an entry worth opening for the people it's actually about.
The changelog page covers the rest, and what a changelog is covers the difference from release notes.
What belongs in a release note covers each section in detail.
14 days, a card at signup, then $9 or $39 a month.
