CHANGELOG.md format, explained line by line

Keep a Changelog 2.0.0 is direct: “Name it CHANGELOG.md.” Put it in the repository root, where people and tools look first. Open with a # Changelog heading and the short preamble from the template, which says what the file is, which format you follow and which versioning scheme you use. Keep a Changelog suggests pinning its link to the version you follow, so it stays accurate as the guidance changes.

Then make it findable from where people install your package. npm renders your README on the package page, so link the changelog from the README; for Python packages, add a Changelog entry to [project.urls] in pyproject.toml. The npm and PyPI guides cover both.

Each release gets a second-level heading with the version in square brackets and the release date: ## [1.4.0] - 2026-10-02. The brackets make the version a Markdown reference link (see below). List the latest version first, and use YYYY-MM-DD dates: Keep a Changelog says the format “orders from the largest unit to the smallest, avoids the confusion of regional date formats, and is an ISO standard.”

Use the version exactly as published to the registry and tagged in git, so a reader, a script or an agent can match the heading to the tag. You don't have to use Semantic Versioning, but say which scheme you use; Semantic Versioning and changelogs explains what each number promises if you do. A version may open with a sentence or two summarizing the release before its typed sections; that's optional.

Under each version, group entries by type, in the order Keep a Changelog lists them, and leave out types with nothing under them. Keep a Changelog keeps it to six “on purpose”: what kind of change it is goes in the type, why it matters goes in the wording.

Unsure between Fixed and Changed? Keep a Changelog's test: “ask whether the old behavior was a bug. If it was, use Fixed.” Dependency updates aren't a type: describe their effect under the right type if users notice it, and leave them out if not.

Keep a Changelog 2.0.0 says breaking changes “usually go under Changed or Removed” with a short Breaking: marker, kept “with the type of change they are” rather than collected into a separate section, so anyone scanning Changed or Removed sees them in place.

### Changed
- **Breaking:** `timeout` is now in milliseconds, not seconds.
  Replace `timeout: 30` with `timeout: 30_000`.

A one-line upgrade note can sit in the entry. When the steps are substantial, link to a migration guide or the release notes instead of spelling them out in the changelog. Release notes and announcements can still gather breaks under their own heading, like the GitHub release in the Markdown release notes templates; in CHANGELOG.md, keep the marker on the entry. Either way, every break needs a migration step. How to document breaking changes covers what to write.

Deprecations come first: “mark it Deprecated in one release, and only Removed in a later one”, and say which version will remove it. See how to write deprecation notices.

• Unreleased. “Keep an Unreleased section at the top to collect upcoming changes.” When you cut a release, rename it to the new version in both the heading and its link, then add a fresh, empty Unreleased section.
• Yanked. A release pulled because of a serious bug or security issue stays listed, marked like ## [1.3.1] - 2026-09-14 [YANKED]. Keep a Changelog: “List it; do not hide it.”
• Link references. Resolve each bracketed version once at the bottom of the file, pointing it at a comparison with the version before. [Unreleased] compares the latest tag to HEAD, and the oldest version links to its tag.
• Corrections. You can fix a forgotten entry or an unrecorded breaking change after a release; Keep a Changelog suggests noting the date you updated the entry.

The changelog can be corrected; the release can't. Semantic Versioning: “Once a versioned package has been released, the contents of that version MUST NOT be modified.” Fix code in a new version and say so in its entry.

Common Changelog is “adapted from and a stricter subset of Keep a Changelog”. Pick one and name it in your preamble.

• Pasting the git log. Keep a Changelog: “Do not use a list of commits as a changelog. It is full of noise.” Draft from commits if you like, then edit; see how to generate a changelog from git.
• One long list per version with no change types, so breaking changes hide among fixes.
• Version headings that don't match the published versions or git tags.
• Dates in regional formats, or no dates at all.
• Recording some changes but not others. Readers treat a changelog as the full picture.
• Inventing new types (Improved, Internal, Dependencies) that readers and tools don't expect.

A quick test: paste the file into the free changelog-to-JSON converter. It's a deterministic parser, not AI, so if a version, a breaking change or a deprecation doesn't show up in its output, the heading or wording is probably the problem.