Changelog
A curated, human-readable record of the notable changes in each version of a project, written for the people who use it rather than the people who built it.
A changelog is a file, conventionally CHANGELOG.md, that lists the notable changes in each released version of a project, newest first. Its audience is the people who use the software: someone deciding whether to upgrade, a maintainer of a downstream package, or a user trying to work out when a behavior changed. That makes it different from the Commit history, which records every step the developers took, including typo fixes, reverted experiments, and merge commits.
The Keep a Changelog convention, published by Olivier Lacan in 2014, is the most widely followed format. Each version gets a heading with its number and release date, written in ISO 8601 form, and its entries are grouped by kind of change:
- Added for new features.
- Changed for changes to existing behavior.
- Deprecated for features that will be removed, giving users warning (see Deprecation).
- Removed for features that are gone.
- Fixed for bug fixes.
- Security for vulnerabilities, so users know how urgently to upgrade.
An Unreleased section at the top collects changes as they merge, and becomes the next version's entry at release time. The categories map onto Semantic Versioning: anything under Removed, or a breaking entry under Changed, implies a major version bump.
The convention's main warning is against dumping the commit log into the file. A list of commit subjects is noise to a user and buries the one change that matters. Writing a good entry means describing the effect on the user, not the implementation, which is harder than it sounds because the author already knows what the change was for, a case of the curse of knowledge. Breaking changes deserve migration instructions, not just a mention, since Hyrum's Law means someone depended on the old behavior.
Tooling can automate much of it. With Conventional Commits, a feat: or fix: prefix tells a release tool which section an entry belongs in and which version bump it implies. A Squash Merge workflow, where each Pull Request becomes one commit, makes those subjects more meaningful. Other tools have contributors add a short change file with each pull request, which is collected into the changelog at release, a pattern common in a Monorepo with many independently versioned packages.
Release notes are the companion form: a narrative summary of a release's highlights, often with screenshots and context, aimed at a broader audience. Large projects publish both. A changelog that isn't kept up is a form of Documentation Rot, and an inaccurate one is worse than none, because readers trust it when deciding what to upgrade. Regular releases on a Release Train keep each entry short.
See also1
Linked from8
- Automated Dependency UpdatesVersion Control & Delivery
Bots that open pull requests whenever a dependency releases a new version, how they keep upgrades small and security patches fast, and how they turn into noise or a supply-chain risk when misconfigured.
- Commit MessageVersion Control & Delivery
The note attached to each change in version control, conventionally a short summary line and a body explaining why, which becomes the main record of intent for anyone who later wonders why the code is the way it is.
- Conventional CommitsVersion Control & Delivery
A lightweight convention giving commit messages a machine-readable type and scope.
- DeprecationMethod
Marking something as superseded and scheduled for removal, without removing it yet.
- Model CardAgents & Language Models
A short standard document published alongside a machine learning model describing what it's for, how it was trained and evaluated, where it performs worse, and what it shouldn't be used for, now routine on model hubs and for frontier releases.
- Release TrainVersion Control & Delivery
Shipping on a fixed schedule whether or not a given feature is ready, so features that miss one release simply wait for the next instead of holding everyone back.
- Semantic VersioningVersion Control & Delivery
A version-numbering convention where the number communicates the kind of change.
- Shallow CloneVersion Control & Delivery
Ways to fetch less than a whole Git repository, by cutting history, deferring file contents, or checking out only some directories, and what each breaks.