Changelog
A changelog is a chronological record of the notable changes made to a project, grouped by version and dated, usually with the newest entry first. It is kept with the code, often as a file named CHANGELOG, and tells developers and integrators what was added, changed, deprecated, removed or fixed from one version to the next.
The longer version
A widely used layout is the Keep a Changelog convention. Each version has a heading with its date, and under it the entries are sorted into Added, Changed, Deprecated, Removed, Fixed and Security. An Unreleased section at the top collects changes as they merge, so the person cutting a release renames it instead of reconstructing history. Versions that follow semantic versioning let a reader judge the size of a change from its number, and breaking changes get a line of their own that nobody has to hunt for.
Where a changelog is edited by hand, its value is the editing. Generated from commit messages it tends to list every typo fix and routine dependency bump, and the one change a reader needs is lost among them. Entries should state what a consumer of the code will notice, including an internal change or a dependency upgrade that alters behaviour for integrators, link the pull request or issue for detail, and leave out refactors with no visible effect.
The audience is the person who maintains or integrates with the code. Release notes, which are written for the end user of each release, are a separate document covered on their own page. Written well, a changelog answers the question a developer asks before an upgrade: what changed since the version I am on, and will it break me.
Common questions
What is a changelog?
A changelog is a file or page that lists the notable changes in each version of a project, newest first and dated. It tells developers and integrators what was added, changed, removed or fixed, so they can judge an upgrade without reading the commit history.
Does a changelog replace release notes?
A changelog does not replace release notes, since the two serve different readers. The comparison is set out on the release notes page.
What format should a changelog use?
A common choice is the Keep a Changelog convention: a heading per version with its date, newest first, and entries grouped under Added, Changed, Deprecated, Removed, Fixed and Security. An Unreleased section at the top gathers changes between releases, and version numbers follow semantic versioning where the project uses it.
Should a changelog be generated from commit messages?
Generation from commits saves time but produces noise, since commit messages are written for other developers and include changes no reader needs. A common compromise is to generate a draft from structured commit messages and have a person edit it before the release is tagged.
Where should a changelog live?
A changelog normally lives in the repository root as a CHANGELOG file, so it travels with the code and is reviewed in the same pull requests. Many products also publish it on a page of their site, which gives users and search engines a stable address for the history.
Bug reports that arrive ready to triage.
Collect replay, console, network and browser context with the Free plan.