Changelog

For a long time products changed every week while the fact that they had changed lived nowhere but in the heads of the people who made them. A month later nobody could say for certain whether a button had always been in that corner. Checking meant walking backward through the code history one entry at a time, and those entries were notes engineers wrote for themselves — hundreds of lines reading like "fix auth token expiry handling," which answers a question nobody outside the codebase was asking.

So every support ticket produced the same scene. A Pagedeck customer writes in to say the export that worked yesterday is failing today. Sofia asks Theo, Theo digs through recent deploys looking for something that might explain it, and an answer comes back half a day later. In the meantime Sofia can only tell the customer she is checking. She can't even tell whether anything changed, so she doesn't know whether to apologize or to explain.

A changelog removes that cost. Write one human-readable line at each release saying what moved, and the next time the question comes up, someone opens the list and points at a date. The record answers instead of memory or archaeology.

An entry carries three things: a version number or date, a label for the kind of change, and one line describing what is different now. The newest entry sits at the top and the list runs backward from there.

1. Version and date, written as something like 2.4.0 — 2026-09-16. Most teams number versions with semantic versioning (SemVer), a convention that encodes the size of a change in three digits: a bump in the first digit means existing usage breaks, the middle digit means a feature was added, and the last means a bug was fixed.
2. A category. Six buckets are common — added, changed, fixed, removed, deprecated, security. A release with ten entries stays readable because each reader can skim only the bucket that concerns them.
3. The change itself in one line, written in terms of what a user experiences: "You can now filter the document list by tag." Something like "Introduced TagFilterService" describes the inside of the build and tells the reader nothing.
4. Blast radius. If existing behavior stops working, the entry says so. A change that breaks code other people wrote is called a breaking change, and an entry for one also says what to use instead.
5. A reference link to the document or issue that explains the change in full, so the line can stay short and only readers who need more follow it.

Dates matter as much as descriptions here. A support conversation almost always starts from a moment — something worked on Tuesday and didn't on Wednesday — so an entry without a date can't be matched against the complaint that prompted the search. For the same reason the list keeps old entries instead of trimming them; a customer on a year-old integration is reading the part most teams would consider stale.

Entries are grouped by release, not by task. If a feature took twelve separate changes and users notice one difference, that is one line. If a single deploy changes two things that different people notice, that is two lines — a new button on screen and a new response format reach different readers.

The person who made the change writes the line. When one person assembles everything after a release, the details have already faded and the result is usually copied commit messages. Pagedeck writes the line at the moment a change is merged and collects those lines when the release goes out.

Readers split into two groups. Inside the company there is Sofia handling tickets, Theo confirming and testing what moved, and whoever assembles a monthly summary for larger accounts. Outside there are developers whose own software talks to the product. The interface a product exposes for other programs to call is its application programming interface (API), and when the shape of that interface changes, the code on the other side stops working. That is why products with an API keep their changelog as public documentation.

The two audiences want opposite things. Inside, the value is completeness. Outside, the only question is whether a given integration is about to break. Many teams keep a full internal list and promote the externally visible entries into a public one. A team without the capacity for two lists keeps one and marks external impact on each entry. Either way the promotion step is a judgment call someone has to own, because an entry that looks internal — a rename inside a response payload, say — can be the one that breaks an integration.

"When did this change? Let me check the changelog."

Stop relying on memory and find the date in the record.

"That change never made it into the changelog."

It shipped but was not recorded. An unrecorded change is one nobody can trace when a ticket arrives.

"We're dropping the old format next version, so put it in the changelog now."

The list also serves as advance notice, not just a record of things already done.

At Pagedeck, Mia reads through the pending entries just before a release. She rewrites the ones still phrased in build terms, and when an entry changes existing behavior she flags it for Sofia first. Sofia then reaches out to the accounts that lean on that feature before they notice on their own.

The order of operations on an incoming ticket is settled too. Sofia finds the date, reads what shipped that day, and follows the reference link on any entry that looks related. Only when nothing matches does she go to Theo. That is where a half-day answer turns into a few minutes.

The most common mistake is treating a changelog as marketing. It is public, so it feels like something that should be presented well. But the list earns its value by being complete. Pick out only the flattering features, leave out the quietly retired ones and the behavior that shifted, and the person who opens it during an incident finds nothing. After that happens once, nobody opens it again.

Saving it up and writing it in a batch is the other one. Each change looks small enough that collecting them later seems efficient. Two weeks on, though, the reasoning is gone and only the outcome remains, so the list fills up with lines like "performance improvements" — lines that answer no question anyone has. Writing the entry costs one line at the moment of the change; reconstructing it later costs far more.