A changelog — a running, human-readable record of what changed in each release of a piece of software — is a small, low-cost documentation habit relative to the amount of trust and clarity it buys, which makes it a somewhat unusual case among documentation practices, most of which involve a more substantial trade-off between effort and payoff. Despite the low relative cost, changelogs are frequently skipped, inconsistently maintained, or generated automatically from commit messages in a form too raw and unfiltered to be genuinely useful to a human reader deciding whether a given update affects them. A maintained format guide is available at Keep a Changelog.
Why a raw commit log isn't a substitute
A common shortcut is treating a project's raw commit history, or an automatically generated list of merged pull requests, as an adequate changelog. This falls short of a genuinely useful changelog in a specific, predictable way: commit messages and PR titles are written for a different audience (other contributors, reviewing the change at the time it was made) than a changelog's actual audience (a user of the software, later, trying to quickly understand what changed between two versions they're considering upgrading between). A commit message like “fix null check in parser” is meaningful to someone who was already following the specific bug; a changelog entry serving an end user needs to say something closer to “fixed an issue where empty input files caused a crash,” translated into the vocabulary and concerns of someone using the software rather than developing it. For teams evaluating how workstation signals fit into broader workflow analysis, this overview outlines one approach.
This is the same underlying distinction the writing-docs guide discussed elsewhere on this shelf makes between reference and task-oriented documentation, applied specifically to the changelog: a raw commit log is closer to an internal reference of everything that happened; a genuinely useful changelog is closer to a task-oriented summary answering the specific question a user actually has — does this update affect me, and if so, how.
What a changelog entry should actually contain
A useful changelog entry is written from the user's perspective rather than the developer's, groups changes by type (commonly something like Added, Changed, Fixed, and Removed or Deprecated — a structure popularized by the widely referenced “Keep a Changelog” convention), and is explicit and prominent about breaking changes specifically, since those are the entries a user most needs to notice before upgrading — connecting directly to the versioning guide discussed elsewhere on this shelf, where a breaking change's classification in the version number is only as trustworthy as the underlying discipline of actually identifying and clearly flagging it.
- Write changelog entries from a user's perspective, translated from the underlying commit or technical detail into what an end user actually needs to know.
- Group entries by type (added, changed, fixed, removed) rather than presenting an undifferentiated chronological list — it lets a reader scan for the category they actually care about.
- Flag breaking changes prominently and explicitly — this is the single most important thing most readers of a changelog are trying to find out before deciding to upgrade.
- Maintain the changelog alongside the code change itself, not as a separate step reconstructed later from memory — the same accuracy problem discussed in the retroactive time-tracking guide on a different shelf applies here: reconstruction from memory is measurably less accurate than a note made at the time.
Why the habit pays off disproportionately to its cost
Compared to most documentation efforts, a changelog entry takes a genuinely small amount of time to write — often just a sentence or two per notable change — while providing outsized value specifically at the moment a user is deciding whether to upgrade, a decision that directly affects adoption of fixes, security patches, and new functionality. A project with a consistently maintained, clearly written changelog makes that decision easy; a project without one forces every user to either read the raw commit history themselves or upgrade blind and find out what changed the hard way.
Read alongside the versioning guide discussed elsewhere on this shelf, a well-maintained changelog is what actually makes a version number's promise verifiable in practice — the number tells a user what category of change to expect; the changelog tells them specifically what it was.