Versioned or dated? How to label a changelog entry
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.
Label a changelog entry with a version number when a reader can find out which version they are running, and with a date when they cannot. That is the whole test. A version number answers one question — is this change in the copy I have? — and it can only answer it for software the reader holds: an installed application, a library, a mobile app, a self-hosted server, an API with versioned endpoints. For a web application everybody uses at the same revision, the answer is always yes, the question never arises, and the date is what the reader actually needs.
A version number is an identifier a reader can compare against something they possess. Semantic versioning gives that comparison a grammar: three numbers in the form major, minor, patch, incremented according to whether the change breaks an interface, adds to it, or fixes it. A reader on 1.3.2 who sees an entry marked 1.4.0 knows two things without reading a word of it — they do not have this change yet, and taking it should not break their integration. That inference is what the number buys, and it is worth a great deal to anyone maintaining code against your product.
A date tells a reader something different and smaller: when the change reached whoever had it first. It supports no comparison against their own copy, which is why a dated entry on a page about installable software leaves the most common question unanswered. It is, on the other hand, always true, always available, and never requires a release process to exist.
A version label is the wrong choice when nothing on the reader's side carries a version. A hosted product that deploys several times a day has no artefact for a customer to inspect, so a number attached to an entry cannot be checked against anything and gets read as a rough ordering at best. Worse, it invites a question the team then has to answer: what is the difference between 2.4 and 2.5, and which one am I on? Inventing a number to fill the slot creates a support conversation that has no ending.
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.
Market4 treats this as a per-entry choice rather than a site-wide one. A changelog entry carries an optional release label — a string such as 1.4.0 — alongside the date every entry has anyway, and the field defaults to nothing. That shape matches how most products actually ship: a stream of dated changes to the hosted application, punctuated by entries that genuinely correspond to a released artefact, such as a command-line tool or an SDK.
| Situation | Label with | Because |
|---|---|---|
| Installed app, library or SDK | Version | The reader can check what they have and compare |
| Self-hosted server | Version | Upgrades are chosen, so the number tells them what they are choosing |
| Versioned API endpoint | Version | Integrators pin to it and need the interface contract |
| Hosted web app, continuous deploys | Date | Everyone is on the current revision, so there is nothing to compare |
| Hosted app with a shipped client | Both, per entry | Client releases get a number, hosted changes get a date |
The failure worth avoiding is a label that implies a promise the product does not keep. A version number implies that versions are things a reader can be on, that they can stay on one, and that moving between them is a decision. If none of that is true for your product, the number is a costume, and the first support ticket asking how to stay on 2.4 is the bill.
Usually not. A hosted product deploys everyone onto the same revision, so a customer cannot be on an earlier version and a number gives them nothing to compare against. Date the entries instead. The exception is a SaaS product that also ships something installable — a command-line tool, a mobile app, an SDK — where those entries can carry the artefact's real version and the rest stay dated.
Yes, and for products that ship both hosted changes and released artefacts it is the accurate arrangement. Every entry carries a date, and the version is an optional label on the entries that correspond to a real release. Market4 stores it exactly that way: an optional release label on the entry, empty by default. Readers learn quickly that a number means an artefact and no number means the hosted product.
It makes the number readable without the prose. Under semantic versioning the three parts are major, minor and patch, and the part that changed tells a reader whether the update breaks an interface, adds to it, or fixes something. An entry labelled 2.0.0 therefore carries a warning before anybody reads the text. That only holds if the numbering is applied honestly, which is a discipline rather than a format.
From the moment the change reached customers, not from the commit. A commit date describes when somebody wrote the code, which the reader does not care about and which can precede the deploy by weeks. Publishing the entry when the change is live keeps the changelog a record of what customers experienced, which is what makes a question about behaviour answerable from 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.
A changelog migration is four decisions, not a copy and paste: where the entries live from now on, what address each one answers at, what happens to the links people already shared, and who writes the next entry.