The short version
- A changelog is a record. Release notes are an announcement. Everything else follows.
- Three moments people read one, and all three are searches rather than browses.
- Every entry owes the reader a date.
- Starting late loses the record permanently. A changelog begun in year three has no years one and two.
A changelog is a dated record of what changed in a product, in order, kept in one place. Release notes are the announcement of one of those changes at the moment it happens.
One is a record and one is an event. Most products need both and most products publish one artefact that tries to be both, which works as long as you know which of the two properties you're protecting when they conflict.
What is a changelog?
A list of entries, each with a date, each saying what changed, newest first, covering the whole life of the product.
Three properties define it and each one is a rule.
It's complete. A changelog with gaps isn't a record. If a month is missing, a reader can't tell whether nothing happened or nothing was written down.
It's dated. The date is the most used field in it. Somebody looking at a changelog is almost always asking when something changed, not whether.
It's in order and it doesn't get rewritten. Entries aren't edited to look better later. A record that's revised isn't a record.
There's one running, not a description of one, 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.
Changelog or release notes?
A changelog is a record and release notes are an announcement, and every other difference below follows from that one.
| Changelog | Release notes | |
|---|---|---|
| What it is | A record | An announcement |
| Covers | Everything, from the beginning | One release |
| Read | When somebody is looking for something | When it arrives |
| Tone | Neutral | Can be enthusiastic, once |
| Fails when | It has gaps | It buries the important item |
| Written for | Anybody, later | The people affected now |
When one artefact does both jobs, the conflict shows up in tone and length. An announcement wants a paragraph of context. A record wants one line. The version that survives is written as a record and sent as an announcement, being neutral, dated, complete, with the consequential item first.
Who reads a changelog, and when
Three moments, and they're all searches, not browses.
"When did this change?" Somebody's workflow broke or improved and they're looking for the date. This is the most common one and it's why the dates matter more than the prose.
"Is this product alive?" An evaluator, three entries deep, reading the dates rather than the content. A changelog with a recent entry does more for an evaluation than most marketing pages.
"Did my thing ship?" Somebody who asked for something, checking. This reader is the reason a changelog entry that names the request rather than the implementation is worth more than one that doesn't.
What a changelog owes the reader
A date on every entry. Without it the record is a list.
Plain words. The reader searching for when something changed doesn't know your internal names for things.
Nothing removed. An entry about something that has since been withdrawn stays, with a later entry saying it was withdrawn. Deleting it makes the record untrustworthy in a way that no single entry is worth.
No gaps you can avoid. A quiet month gets a short entry rather than silence.
What it does not owe the reader
Every commit. A changelog is about change from the outside, not work.
Completeness about internals. A refactor with no visible effect isn't a change in the sense a changelog means.
Consistency of length. Some releases are one line. That's a true fact about the month and hiding it helps nobody.
The mistakes
Starting it late. A changelog that begins in year three has lost the record for years one and two permanently.
Keeping it in a repository nobody outside can read. Then it's a developer artefact rather than a product one.
Writing entries from the commit log. The reader can't tell which merged branch affected them.
Editing old entries to look better. The one thing that destroys the artefact.
How do you do this without a tool?
One markdown file, newest at the top, a heading per release with a date, a grouped list under each. Commit it with the release.
That's a complete and honest changelog and many products need nothing more. What the file can't do is connect an entry back to the people who asked for the thing in it, so nobody who requested a feature finds out from the file that it arrived.
How does this product do it?
The changelog is a list of releases. A release carries a name, a published date, a markdown body, a featured flag that pins it to the top, and the items that went into it.
The items are the cards that reached the completed column of the board, each with its heading, its category, and the number of people who voted for it.
That connection is the part a markdown file can't do. The people who asked for a thing are known, so the entry announcing it's attached to them, not published into the air.
The banner that announces the newest release strips the formatting out of the body and cuts it at 120 characters, so the first sentence of an entry is the part almost everybody sees.
The changelog page covers the rest, and how to keep a changelog people read covers the cadence.
What release notes are covers the announcement half of the pair.
14 days, a card at signup, then $9 or $39 a month.