Changelog entries fall into a handful of types, and the reason it matters is that different types are read by different people for different reasons.
A release written as one undifferentiated list forces every reader to scan all of it to find the part that concerns them, which is why so many changelogs are published and so few are read. Grouping by type is the cheapest improvement available to almost every changelog on the internet.
What types of changelog entry are there?
Four carry almost all of the value, and a fifth exists and should usually be left out.
New. Something that did not exist before. This is the type people subscribe for and the type that deserves a sentence about why rather than only what.
Improved. Something that existed and now works better, faster or in more places. The commonest type and the one most often written too vaguely to mean anything.
Fixed. Something was broken and is not any more. Short, specific, and worth naming the symptom rather than the cause, because the reader recognises the symptom.
Deprecated or removed. Something is going away or has gone. Rare, and the only type where the date matters more than the description.
The fifth is internal work with no visible effect. It belongs in a commit history rather than a customer changelog, and including it is the fastest way to teach people that your changelog is not worth opening.
Should a changelog be grouped by type or by feature area?
By type for a release note, by area for a large product, and by neither if the release is small.
Grouping by type works because the reader's question is usually what kind of thing changed. Somebody who has been waiting for a fix scans for fixed. Somebody evaluating the product scans for new.
Grouping by area starts to win when a product is large enough that most readers only care about one part of it. A billing administrator does not need to read three paragraphs about the mobile experience, and once that is true for most of your audience the grouping should follow.
For a small release neither helps. Four lines in a list are read in full whatever order they are in, and adding headings to four lines is decoration.
How much detail belongs in a changelog entry?
One sentence on what changed and, for anything new, one on why.
The why is the part that is almost always missing and almost always the reason a reader cares. A line saying the export now includes vote dates is a fact.
A line saying the export now includes vote dates so you can see when demand for a request built up is a reason to go and use it.
The limit on the other side is real. An entry that runs to a paragraph is a blog post trapped in the wrong format, and it should be a link. What separates a changelog from release notes is written up separately, and the difference is largely about how much detail the format can carry.
Who should each type be sent to?
New goes to everybody. Fixed goes to the people who reported it. Removed goes to the people using it.
That distinction is where most changelog tooling stops short. Broadcasting every type to every customer trains people to ignore the channel, and the type is the best available signal for who should get an interruption rather than a page they can visit.
The sharpest version of this is not a type at all, which is telling the specific people who requested a thing that it has landed.
Those messages are read at a rate no general announcement matches, and they are only possible if the request and the release are in the same system. How the changelog is written and published here is on its own page.
What makes a changelog worth reading at all?
Being published on a rhythm somebody can predict, in a place they can find twice.
Type, grouping and tone are all secondary to that. A plain list published every fortnight beats a beautifully categorised one published when somebody remembers, because the first one becomes a habit and the second one is a surprise every time.
The other durable half is that the entries connect back to the asking. A changelog that links a shipped item to the request it came from closes a loop customers can see, and that loop is what makes filing the next request feel worth the trouble. The customer feedback loop is written up separately.
14 days, a card at signup, then $9 or $39 a month.
