Changelog

Origin & evolution

Software always tracked changes somewhere, in commit messages, ticket systems, and ad-hoc release🚢ReleaseProduct SpecificationA shipped version of the productView reference → announcements, but the formats were inconsistent and frequently unreadable. The most influential attempt to standardise the human-facing version was Keep a Changelog, created by Olivier Lacan and developed openly on GitHub from around 2014. It made a simple, opinionated case: stop generating changelogs by dumping git log, because commit messages are written for machines and other developers mid-task☑️TaskProduct SpecificationA unit of work within a story or epicView reference →, not for the person trying to decide whether to upgrade.

The convention's lasting contribution is its small set of change categories: Added, Changed, Deprecated, Removed, Fixed, and Security. That vocabulary turns a flat list into something scannable, and it pairs naturally with Semantic Versioning, since the categories map onto the major, minor, and patch decisions⚖️DecisionStrategyA recorded decision with context, rationale, and consequencesView reference → a maintainer has to make anyway. A "Removed" entry signals a breaking change; a "Fixed" entry signals a patch. The format also insists on an "Unreleased" section at the top, so changes accrue in human form as they land, which spares anyone reconstructing them in a panic at release time.

The live debate is less about format and more about audience, because three documents are easy to confuse. A changelog targets developers and technical users and stays terse and complete. Release notes target end users and customers, written in friendlier prose with screenshots and emphasis on benefits. A commit log is the raw, exhaustive machine record from which both are distilled. The same release can warrant all three, each written for a different reader; the failure mode is publishing one and pretending it serves all of them. Tooling has pushed toward generating changelogs from structured commits (Conventional Commits and similar), which keeps them current but reintroduces the original risk🎲RiskComplianceA risk to the product or businessView reference →: a machine-generated changelog drifts back toward a commit dump unless someone still does the curation.

How it works in practice

A team ships an open-source SDK on a two-week cadence. Every merged pull request adds a one-line entry under the "Unreleased" heading, filed under Added, Changed, Fixed, or Security. On release day the maintainer renames "Unreleased" to 2.4.0 with the date, scans the accumulated entries, and notices three of them under "Changed" describe one breaking rename of an authentication method. That single observation👁️ObservationUser ResearchA specific behaviour or statement observedView reference → forces the version to 3.0.0 where the cadence had assumed 2.4.0, and the maintainer writes a short migration note inline. A downstream team reading the changelog sees the Security fix and the breaking change in ten seconds and schedules the upgrade. None of that is available from the commit log, where the same information is spread across forty messages written for reviewers.

Changelog vs. its neighbours

• Release is the event the changelog documents. A release is a moment in time when a version ships; the changelog is the standing record that accumulates one entry per release. The release is the thing; the changelog is its written history.
• Release notes share the changelog's source material and split on audience. Notes are marketing-adjacent prose for end users; the changelog is a precise technical record for developers. Same facts, different reader, different voice.

April Dunford's account of product positioning🎪PositioningGo-To-MarketProduct positioning statementView reference → makes a narrower but related point: a product's value is never read in a vacuum, because customers judge it against the competitive alternatives and market category they already have in mind, so the same capability💪CapabilityStrategyAn ability that enables value deliveryView reference → lands differently depending on the frame of value the reader brings. Read alongside this entity's own audience split — terse technical record for developers, benefit-led prose for end users — that suggests one way to see why the split exists at all: what counts as a notable change is partly a question of whose frame of value you are writing inside, which is why the same shipped item can warrant a flat 'Fixed' line in the changelog and a benefit-led sentence in the release notes without either being wrong.

• Feature⭐FeatureProduct SpecificationA product capability or featureView reference → is what a changelog entry frequently announces, but the mapping is loose. One feature may span several entries across versions, and many entries (bug🐛BugProduct SpecificationA defect or unexpected behaviourView reference → fixes, security patches) describe no feature at all.

In the graph

In the Unified Product Graph, a changelog sits in the product specification📋SpecificationFoundationsA canonical open standard or specification that primitives and products conform toView reference → region as the human-readable history of what shipped. The relationship to releases is modelled both ways: release_documented_in_changelogReleasedocumented inChangeloghierarchy and changelog_documents_release capture that a changelog is the standing record across many release events. changelog_includes_featureChangelogincludesFeaturesemantic links entries to the features they announce, so a feature's arrival in the product is traceable to the version that carried it. Holding the changelog as its own node, connected to releases and features and collapsed into neither, preserves the distinction the practice is built on: the changelog is curated narrative about change, and the graph keeps that narrative answerable to the actual releases and features behind it.