Publish it, and write it from the symptom rather than from the cause. A bug nobody reported is not a bug nobody hit — most people who run into something broken work around it and say nothing — so the reader of the entry is asking one question: did this happen to me, and is there anything left for me to do? An entry that answers that is worth publishing. An entry that says a null reference was fixed in the renderer answers a question nobody asked.
A changelog that only records fixes somebody complained about is a record of your support queue, not of your product. Three things follow from publishing the silent ones as well. Readers who hit the problem and never wrote in get an explanation for something they half-remember. People deciding whether to trust the product see a log where things get found and fixed rather than one where nothing ever breaks. And when somebody does eventually write in about it, there is a dated entry to point at instead of a conversation to have from scratch.
An entry for an unreported bug needs four things and can leave out everything else. It needs the symptom in the reader's vocabulary — what looked wrong on screen or in the data. It needs the conditions, so a reader can decide whether it applied to them: which page, which browser, which plan, which kind of account. It needs the window, because a reader who exported a report last Tuesday needs to know whether last Tuesday was inside it. And it needs the residue: whether anything they saved during that window is still wrong, and what to do if it is.
The tag on such an entry is FIX, which is one of four this product defines alongside NEW, IMPROVEMENT and REMOVED. A short tag list is a feature here: it stops a fix from being quietly reclassified as an improvement because the word sounds better, and a reader scanning a page can filter to the fixes without reading prose.
The difference between a cause-first entry and a symptom-first entry is not tone, it is whether the reader can act. A cause-first entry is written from the commit; a symptom-first entry is written from what the reader could have observed. The same fix, written both ways, answers different numbers of questions.
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.
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.
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.
| What the reader wants to know | Written from the commit | Written from the symptom |
|---|---|---|
| Did this affect me? | Unanswerable | Named page, named condition |
| When was it happening? | Absent | A start and an end |
| Is my saved data wrong? | Absent | Stated either way |
| Do I have to do anything? | Absent | Yes, and what — or nothing |
| What broke internally? | Answered | Left out, on purpose |
Not every fix belongs in a changelog, and the test is observability rather than size. If no user could have noticed the defect — a race that never fired in production, a typo in an internal log line, a test that was asserting the wrong thing — the commit log is the right home for it and the changelog entry would be noise dressed as transparency. If a user could have noticed, it belongs in the log even if none of them said so.
Security fixes sit slightly apart from this test. A security fix is still a fix and still gets the FIX tag, but how much of the mechanism to describe is a judgement made per entry: enough that an affected reader can tell whether to rotate a credential or check an audit trail, and not so much that the entry is a set of instructions for reproducing the hole on somebody who has not updated.
An entry for a silent fix fits comfortably in a few lines, and keeping to a fixed shape means the decision to publish stops being a writing task. The order below puts the reader's question first and the engineering last, which is the opposite of the order the work happened in.
Yes, if a user could have observed it. Most people who hit a broken feature work around it silently, so the absence of reports says very little about the number of people affected. Publish the entry from the symptom and the conditions so a reader can work out whether it touched them. The exception is a defect with no observable symptom, such as an internal log typo, which belongs in the commit history instead.
Enough that a reader can answer three questions: did this affect me, when was it happening, and is anything I saved still wrong. That usually means the symptom, the conditions, the dates and the remedy. The internal cause is optional and usually unhelpful, with one exception: when knowing the cause is what lets a reader judge how far the problem reached, a single sentence about it earns its place.
FIX. In this product the tag list is NEW, FIX, IMPROVEMENT and REMOVED, and keeping it short is deliberate: a fix stays labelled as a fix rather than being softened into an improvement because the word reads better. A short list also makes the page filterable, so a reader who only wants to know what broke and got repaired can see exactly that.
Say so plainly, in the first sentence, and say what was done about it. A reader whose export, report or saved record went through the affected window needs to know whether the stored value was repaired, whether they should re-run something, and by when. Burying data loss under a line about improved reliability is the version of this entry that costs trust rather than building it.
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.
