Changelog format: three conventions, three real examples, and how to pick one

Keep a Changelog defines a changelog as a curated, chronologically ordered list of the notable changes for each version of a project, kept as a file in the repository. Common Changelog adds one prerequisite: every released version has a corresponding git tag. The benefit: a reader decides whether to upgrade without reading your diff.

The three are not variations on formatting. They disagree about who writes an entry and when. Keep a Changelog and Common Changelog assume a person sits down at release time and writes for readers. conventional-changelog assumes a tool reads structured commit messages and emits the file.

That also answers what the different types of changelogs are. Inside the file, the types are the change categories. Outside it, the split is between the repository changelog, the release notes for one version, and a hosted product changelog page. The release notes versus changelog post covers that split.

Version 2.0.0 shipped on 2026-06-07. Its own release entry states that the six change types, YYYY-MM-DD dates, and the Unreleased and YANKED markers are all unchanged, so an existing file stays valid; only the guidance around the format changed. The site root still serves 1.1.0 as its canonical page, so both numbers are in circulation.

The six types are Added for new features, Changed for changes in existing functionality, Deprecated for soon-to-be removed features, Removed for now removed features, Fixed for bug fixes, and Security for vulnerabilities. There are only six on purpose: the 2.0.0 guidance is explicit that Dependencies is not a type of change, and that a faster JSON parser belongs under Changed, not a new Performance section.

If the old behaviour was a bug, use Fixed; if it was intentional and you are changing it, use Changed. Lead a Security entry with its CVE identifier so security tools can match it to the advisory.

Common Changelog is a style guide adapted from, and a stricter subset of, Keep a Changelog. Four categories replace six: Changed, Added, Removed and Fixed, in that order. Deprecated and Security are gone, and a deprecation is listed under Changed.

In their place come stricter rules. Every change must reference the relevant commit, and should reference the ticket or pull request when one exists, written after the change on the same line, in parentheses. Author names follow the references. Breaking changes carry a bold Breaking prefix and sort first within their category. Entries use the imperative mood and must be self-describing, as if no category heading existed: write Add write() method, not write() method.

There is no Unreleased section: a contributor cannot add the reference to their own change, because it only exists after the fact. Yanked releases get a one-sentence notice rather than a YANKED tag, which the spec concedes is more generic but unparsable. The cost: every entry is hand written at release time, by someone holding the whole release in their head.

conventional-changelog generates a changelog from git metadata. Install it alongside a preset and pass the preset name, for example conventional-changelog -p angular, which reads commits since the last matching semver tag and does not overwrite previous changelogs. Its documentation recommends using a commit convention so the tool can tokenize commits. That convention is usually Conventional Commits, whose 1.0.0 specification maps fix to PATCH, feat to MINOR, and any commit carrying BREAKING CHANGE to MAJOR regardless of type.

The output is recognisable, and it is not Keep a Changelog. Version headings are links to a compare diff with the date in parentheses, sections are named Features and Bug Fixes, and breaking changes collect into their own section instead of sitting with the change they break.

Both other conventions argue against generating the file. Keep a Changelog 2.0.0 states that a commit and a changelog entry are written for different people, and that a generated changelog is raw material at best. Common Changelog lists Conventional Commits as an antipattern, because using it still means converting commit messages into a more readable form. The counterargument is short: a generated changelog exists, and an unwritten one does not.

The constraint is effort per release, not aesthetics. Common Changelog produces the best file and asks the most of you. conventional-changelog asks almost nothing and produces the weakest file. Keep a Changelog sits between them, and is the safe answer when you are unsure.

Whichever you pick, declare it in the preamble. Keep a Changelog's guidance is that stating your conventions tells readers, and tools, what to expect. Pin the link to the version you follow so it stays accurate as that page changes. Neither spec needs a changelog tool installed to start.

Keep a Changelog 2.0.0 frames this as curating rather than accumulating: a changelog records notable changes, which means some changes are not notable. It warns the other way too. A changelog that records only some changes can mislead as much as no changelog, because readers treat it as the full picture.

The test that resolves most cases: would someone who uses the distributed software notice, or need to act? Common Changelog turns that into an exclusion list, and a shorter list of things that look like noise and are not.

Two habits do the most damage. Ignoring deprecations: mark something Deprecated in one release and only Removed in a later one, and say which version will remove it. And pasting a commit list, which records steps in the evolution of source code, not the differences that matter to the people using it.

Write the heading as the version number and the date in YYYY-MM-DD form. Keep a Changelog's reasons for ISO order: it runs from the largest unit to the smallest, avoids regional formats where month and day swap places, and is an ISO standard. Common Changelog requires the same format.

The square brackets around the version make it a Markdown reference link, resolved once at the bottom of the file. Point each version at a comparison with the one before it, and Unreleased at HEAD, so every version is tied to its tag and links to the exact diff. Any host exposes tag and comparison URLs, so the pattern survives a move to a different one.

Semantic Versioning 2.0.0 decides which number moves. Under 0.y.z the spec says anything may change at any time and the public API should not be considered stable, which is when a changelog is doing the most work.

Common Changelog makes the location a hard requirement: the filename must be CHANGELOG.md and the content must be Markdown starting with a first-level heading. Keep a Changelog allows HISTORY, NEWS or RELEASES but says a predictable name makes it easy to find. There is no special GitHub changelog format: a GitHub changelog is CHANGELOG.md at the repository root, with version headings resolved to GitHub compare URLs at the bottom.

Is changelog one word or two? One word. Keep a Changelog records the decision in its own 1.0.0 entry: start using changelog over change log, since it is the common usage. Write the file name in uppercase and the word itself in lowercase in prose.

In a monorepo, unrelated projects sharing a repository each keep their own file, while one product made of many parts can keep a changelog per component but should also keep one central changelog. A hosted product changelog page, or an app changelog inside the product, is a separate artifact generated from this file rather than replacing it.

Land changes, add the notable ones to Unreleased, and at release time rename Unreleased to the new version in both the heading and its link, add the date, then add a fresh empty Unreleased pointing at HEAD. Common Changelog adds one ordering detail worth copying: commit the changelog entry before you create the git tag, so the tag contains its own entry.

Keep a Changelog 2.0.0 says to use continuous integration for mechanical tasks: moving Unreleased into a dated version, checking formatting, reminding a contributor that a change may need an entry. Do not make a changelog edit a required check on every pull request, because that teaches people to add a line to pass the check, which fills the file with noise.

Because every version sits under a predictable heading, that section is already the draft of its release notes, and a few lines of awk pull it out.

Once CHANGELOG.md is the source of truth, the work that repeats every release is turning one version section into posts for wherever your users are. Ship 2 Post watches your repository for releases, tags, merged pull requests and deployments through its GitHub App, drafts channel-native variants in a brand voice you configure, and queues them for one-click approval before anything publishes to any of its 14 destinations. The free plan is one post per UTC day, no credit card.