What to write when the release is one bug fix
The reader of a bug-fix entry is asking one question: did this happen to me, and is anything I am holding still wrong? Four sentences can answer it.
When the release is one bug fix, write the symptom in the words the customer would have used, say who was affected and between which dates, say whether anything they are holding is still wrong, and say whether they need to do anything. Four sentences is usually enough. The reader of a bug-fix entry is not curious about your code; they are checking whether the strange thing they noticed last week was you, and whether the numbers they exported are safe to use. An entry that does not answer that leaves them exactly where they started.
A changelog line that reads "fixed a bug" tells the reader nothing they can act on, and it costs them the effort of reading it. It does not say what went wrong, so nobody can recognise their own experience in it. It does not say who was affected, so everybody has to assume it might have been them. It does not say whether the effect persists, so anybody holding an export, a report or a saved view is left guessing. The same is true of "minor fixes and improvements", which is a sentence that exists to fill a release, not to inform one.
There is a real alternative to writing a vague entry, and it is writing no entry at all. A fix for a defect that never reached customers does not belong in a customer changelog, and saying so is a decision rather than a lapse. What is not acceptable is the middle ground, where something happened to people and the record of it is a line that could describe anything.
An unreported bug is not an unexperienced bug. The entry that earns its place describes the symptom a reader might have seen, the conditions it happened under, and whether there is anything left for them to do.
Market4 turns one release note into a changelog page, a blog post, a mail-out and a week of social posts — and then tells you which of them brought anyone back.
| Question the reader has | The vague entry | The written entry |
|---|---|---|
| What broke? | Fixed a bug in exports | CSV exports of the weekly report contained no rows when a date filter was applied |
| Was it me? | Unstated | Affected exports run with a custom date range between 2 and 9 September |
| Is my data wrong? | Unstated | Reports in the product were correct throughout; only the downloaded file was empty |
| What do I do? | Unstated | Run the export again; no other action is needed |
| How long to read | Five words that answer nothing | Four sentences that end the question |
The most consequential thing a bug-fix entry can say is whether stored data was affected, because that determines whether the reader has to redo work. A display bug and a data bug read the same way in a release note and mean completely different things to somebody who exported a report on Tuesday. Be explicit about which one it was, and be explicit about the repair: figures recalculated for the affected period, figures corrected from today onwards, or nothing to correct because the underlying records were always right.
Where a correction changes numbers people have already seen, say that plainly and give the size and direction of the change if it is knowable. A reader who finds a total different from the one they screenshotted will assume something else is broken unless the entry told them to expect it. A note that says the figures for that week moved, and in which direction, is the difference between a correction and a new incident.
The internal cause of a bug belongs in a customer entry when it changes what the reader should do, and not otherwise. If people invented a workaround while the defect was live — avoiding a filter, re-uploading a file twice, keeping a browser tab open — name the cause so they know the workaround can be dropped. If the cause is a detail of your own architecture with no effect on anybody's behaviour, leaving it out is not evasive, it is editing. The test is whether the sentence changes a decision on the reader's side.
Tagging follows the same logic. A single fix is tagged as a fix, and a release that repairs something by removing a feature is not a fix, whatever the ticket said. Market4 records each entry under one of four tags — new, fix, improvement, removed — and choosing the honest one matters more than choosing the flattering one, because readers filter on tags and a mislabelled removal is how somebody misses that a capability they relied on is gone.
Email a bug-fix entry when the reader has an action to take or a reason to distrust something they already have. A fix that corrects historic figures, restores a broken integration, or removes the need for a workaround is worth an inbox. A fix for something almost nobody hit, with no lingering effect, is not: it belongs in the changelog where somebody looking for it will find it, and nowhere else. Sending everything trains people to open nothing, which costs you the one message that mattered.
No. A fix for a defect that never reached customers has no reader, and publishing it adds noise to a page people scan for things that affected them. The test is whether anybody outside the team could have noticed the behaviour. If they could, the entry is owed to them; if they could not, the fix belongs in your internal history and the decision to omit it should be a decision somebody made, not an oversight.
Detail becomes too much when it stops changing what the reader does. The symptom, the affected group, the date window, the state of their data and the required action all change decisions. The name of the internal function, the version of the library and the shape of the regression test do not, unless one of them retires a workaround people adopted. Write for somebody deciding whether to redo an export.
Say what you do know and mark the boundary of what you do not. "Affected some accounts using scheduled reports between 2 and 9 September; we cannot identify the exact set" is honest and still useful, because it narrows the question. Implying certainty you do not have is worse than admitting the gap, because the first person who finds themselves outside your stated window will stop believing the rest of the page.
A short acknowledgement is fine and a long apology is not, because it displaces the information the reader came for. Put the facts first: symptom, scope, data, action. If an apology belongs anywhere it is one clause at the end. Readers judge a changelog by whether it told them what happened, not by how sorry it sounded, and an entry that leads with regret usually buries the part they needed.
State that figures for a named period were recalculated, say which direction they moved if that is knowable, and say whether anything already exported is affected. Anybody comparing a saved screenshot with the corrected figure needs to know the difference came from you. Without that sentence, a correct repair looks exactly like a new defect, and the support conversation you avoided by fixing it happens anyway.
Most deploys do not deserve a changelog entry, and publishing one per deploy turns the page into a build log. A four-question test for which ships earn an entry, what to do with the ones that fail it, and why silence is a correct output.
Somebody deciding whether to buy your product reads the changelog for something your marketing pages cannot tell them: whether anyone is still working on it, and what happens to them when something changes.