When you ship twenty times a week, the hard part of a changelog is not writing entries, it is deciding which ships earn one. The unit of a changelog entry is a user-visible change, not a deploy, and most deploys do not produce one. A dependency bump, an internal rename, a refactor, a fix for a bug that lived for forty minutes: all shipped, none worth an entry. Publishing one entry per deploy turns the page into a build log, and a build log is a page customers stop opening.
A four-question test settles most cases in a few seconds, and the order of the questions matters. The first question decides whether there is an entry at all. The other three decide whether the entry you have drafted is finished.
Question one is a gate and the other three are edits. Failing question one means the change is invisible from outside and belongs in your commit history, where it already is. Failing questions two, three or four means the change is real and the sentence is wrong, which is a rewrite rather than a deletion.
Nothing happens to them, and that is the answer people find hardest at a high shipping cadence. Silence is a correct output for a changelog. A page that reports every deploy is measuring the team's activity rather than the customer's experience, and once it does that, its readers become the team — the audience it was never written for. Twelve deploys and one entry is a normal week for a product with a healthy release rhythm and a strict filter.
| What shipped | Entry | Why |
|---|---|---|
| A new export button on the reports screen | Yes | A customer can see it and use it |
| A dependency upgrade with no visible effect | No | Nothing observable from outside changed |
| A fix for a crash three customers reported | Yes | Those three will look for it, and others hit it silently |
| A bug found and fixed within the hour | No | Nobody outside the team met the old behaviour |
| A rename of an internal service | No | The entry would have to name a component customers do not know |
| A setting that now defaults the other way | Yes | Behaviour changed for everyone who set nothing |
| A field removed from an API response | Yes | Somebody's integration breaks on it |
| A page that got faster in a way nobody would notice | No | If it is unnoticeable, there is nothing to announce |
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.
A version label answers one question: is this change in the copy I have? If your readers cannot check that, the number is decoration and the date is the label.
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.
Shipping continuously removes the release as a unit, and the changelog should stop pretending otherwise. There is no Tuesday version to describe, so an entry describes one change and carries its own date. Grouping entries by day or by week is a rendering decision the page makes when it draws itself; it is not an editorial decision to hold three finished entries until Friday. The distinction matters because a held entry ages: by Friday the person who made the change has moved on and the sentence gets written from a diff instead of from memory.
This is also the practical difference between a changelog and release notes. Release notes describe one release in depth and need a release to exist. A changelog is a continuous log of user-visible changes and needs only a change. At twenty ships a week you have the second and not the first.
A short tag vocabulary is worth keeping because it decides who hears about an entry, not because it files it neatly. In this product an entry carries any of four tags, and the publish step can request the subscriber email with a tag filter, so the tag on an entry is the thing that decides whether a given subscriber is told. Treated that way, arguments about whether something is a fix or an improvement stop being taxonomy debates and become a question with an answer: who should get an email about it.
Draft the entry with the change and publish it when the change is live. Writing the sentence while the behaviour is still in your head produces a description of what a customer will notice; writing it a week later from a list of merged branches produces a description of what the team did. Drafting and publishing being two separate steps is what makes this work: the draft can exist for days while the change waits behind a flag, and the publish is a single action taken the moment it is true.
No. The unit of an entry is a user-visible change, and most deploys do not contain one. Dependency upgrades, refactors, internal renames and bugs that existed for an hour all ship without anyone outside the team noticing a difference, and an entry for each of them turns the page into a build log. Publish for the changes customers can observe, and let the rest live in your commit history.
Write the entry as part of the change rather than as a weekly chore, and apply a strict filter so most changes need no entry at all. Drafting the sentence while the behaviour is fresh takes a couple of minutes and produces a better description than reconstructing it later from a list of merged branches. The volume problem usually turns out to be a filtering problem.
Yes. A quiet week on a changelog means no change reached the point where a customer would notice it, which is ordinary and worth being honest about. Manufacturing an entry to fill the gap trains readers to skim, and the next real entry gets skimmed with it. A changelog earns attention by being reliably worth reading, not by being reliably updated.
The person who would have to answer the support ticket. That test cuts through most arguments, because it replaces "is this significant" with "would somebody write in about this, either to ask what happened or to ask when it is coming". If the answer is yes, it is user-visible and it needs an entry written in the words that person would use.
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.
