Changelog Example: Annotated CHANGELOG.md for 2026

November 11, 2026 · 12 min read

Changelog Example: How to Write a CHANGELOG.md People Actually Read

A good changelog example is a CHANGELOG.md file that lists notable changes per version, newest first, grouped as Added, Changed, Deprecated, Removed, Fixed and Security, with ISO dates. Below you'll find one annotated file in the current Keep a Changelog 2.0.0 format, then real changelogs from React, Vite and Angular.

What Is a Changelog?

A changelog is a curated, newest-first record of the notable changes in each version of a project. It usually lives as CHANGELOG.md in the repository root. Users read it before upgrading, and contributors read it to see what shipped.

It isn't your git log. A commit records one step in the code, while a changelog entry describes a difference someone using the software will notice. It also isn't the same as release notes, which announce a single release and are usually drawn from the changelog. If you only want a blank file to copy, our Markdown templates collection has a bare CHANGELOG skeleton. This post is about filling one in well.

What Does a Changelog Look Like? A Full CHANGELOG.md Example

Here's a complete changelog example for a small web app. It follows Keep a Changelog 2.0.0 and uses every convention you're likely to need.

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/2.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- Dark mode for the settings page.

## [2.0.0] - 2026-11-03

Exports got a rewrite: CSV is a first-class format and the API now speaks JSON.

### Added
- CSV export from the reports screen.

### Changed
- **Breaking:** The export endpoint returns JSON instead of CSV. Add ?format=csv to keep the old output.

### Deprecated
- The legacy_export setting. It will be removed in 3.0.0.

### Fixed
- Dates no longer shift by one day for users east of UTC.

## [1.3.1] - 2026-10-14 [YANKED]

### Fixed
- Report totals now include refunded orders.

## [1.3.0] - 2026-10-02

### Added
- Weekly email digest for account owners.

[Unreleased]: https://github.com/example-org/example-app/compare/v2.0.0...HEAD
[2.0.0]: https://github.com/example-org/example-app/compare/v1.3.1...v2.0.0
[1.3.1]: https://github.com/example-org/example-app/compare/v1.3.0...v1.3.1
[1.3.0]: https://github.com/example-org/example-app/releases/tag/v1.3.0

What each part does:

  1. The preamble says what the file is and which conventions it follows. Pinning the link to 2.0.0 keeps that statement accurate if the guidance changes later.
  2. [Unreleased] collects changes as they merge. Readers see what's coming, and release day becomes a rename.
  3. Version headings pair the number with a YYYY-MM-DD date. The square brackets turn each heading into a reference link.
  4. The one-line summary under 2.0.0 is optional. Use it when a release has a theme worth stating.
  5. The Breaking prefix (**Breaking:**) marks the entry that will break someone's code. It stays under Changed rather than moving to a separate section.
  6. [YANKED] flags 1.3.1 as pulled. You keep the entry visible instead of deleting it.
  7. The link definitions at the bottom point each version at a compare diff, [Unreleased] at HEAD, and the oldest version at its tag.

On GitHub, each version heading renders as a link to the exact diff for that release. The example-org URLs are placeholders, so swap in your own repository.

Keep a Changelog 2.0.0: What Changed in the Current Version

Keep a Changelog 2.0.0 was published on June 7, 2026. It's the first major revision of the convention, and its own changelog is clear that the guidance changed while the format did not. The six change types, ISO dates, the Unreleased section and the [YANKED] marker are all unchanged, so a file written to 1.1.0 is still valid.

The principles stay short: changelogs are for humans, every version gets an entry, newest goes first, and each release shows its date. What 2.0.0 adds is guidance for questions people kept asking:

  • Breaking changes get a short **Breaking:** prefix on the entry itself, usually under Changed or Removed. Substantial upgrade steps belong in a linked migration guide.
  • Choosing a type comes down to one question: was the old behaviour a bug? If yes, it's Fixed. If it worked as intended and now works differently, it's Changed.
  • Security entries lead with the CVE identifier when there is one.
  • Dependency bumps aren't a type. Describe their effect under the right type, or leave them out.
  • Compare links at the bottom of the file tie each version to its diff.
  • Versioning schemes other than SemVer are fine, as long as the preamble names the one you use.

The new section on automation sums up the stance in one line: "machines can draft, but humans curate." That applies to language models and to commit-based generators alike.

Changelog Examples From React, Vite and Angular

Big projects don't all follow Keep a Changelog. These three come from real, busy repositories, and side by side they show the trade-offs between curated and generated entries. Each excerpt is a simplified sketch of the file's shape as of November 2026, not a copy.

React: curated by people. Minor releases such as 19.3.0 open with highlight sections like New React Features and Notable changes, then an All Changes section split by package. Patch releases skip the highlights and list a few fixes under a package heading.

## 19.3.0 (September 9, 2026)

### Notable changes
- Short, plain description of the change (@author #12345)

### All Changes

#### React DOM
- Fixed a warning that fired twice for an edge case (#12346)

It reads well and credits contributors. The trade-off is the date format: September 9, 2026 is friendlier to read but harder for tools to sort than 2026-09-09.

Vite: generated from Conventional Commits. The Vite changelog links every version heading to a compare diff. Entries sit under Bug Fixes, Features, Performance Improvements, Miscellaneous Chores, Code Refactoring and Tests.

## [8.3.8](https://github.com/vitejs/vite/compare/v8.3.7...v8.3.8) (2026-11-11)

### Bug Fixes
* **css:** subject line of the fix commit (#1234) (abc1234)

### Miscellaneous Chores
* **deps:** update a dependency (#1235) (def5678)

The bold scope tells you which area changed, and every line links to its pull request and commit. The cost is noise: dependency updates, lint-rule chores and even reverted commits appear next to real fixes.

Angular: generated tables per package. Angular's CHANGELOG.md gives each package (core, forms, router and so on) a table of commit hash, type and description. Larger releases add separate Breaking Changes and Deprecations sections in prose.

### forms
| Commit | Type | Description |
| -- | -- | -- |
| abc1234567 | fix | support blur updates for custom controls |

Tables scan fast when a framework ships many fixes in every release. They're hard to read for anyone who doesn't already know the codebase. Still, if you run a monorepo, Angular's file is the changelog example to study for grouping one release by package.

How Do You Create a Changelog?

Starting one takes a few minutes, and keeping it current takes one line per notable change:

  1. Create CHANGELOG.md in the repository root and add the # Changelog heading and preamble from the example above.
  2. Add ## [Unreleased] and log each notable change under the right type as you merge it.
  3. At release time, rename Unreleased to ## [x.y.z] - YYYY-MM-DD, then update its link definition at the bottom. Our semantic versioning guide has a decision rule for which number to bump.
  4. Add a fresh, empty [Unreleased] section pointing at HEAD.
  5. Link the file from your README so people find it. Our README Markdown guide covers how to structure the rest of that file.

Joining a project that never kept one? Start recording from your next release. Rebuilding older versions from the git history is optional, and Keep a Changelog treats either choice as fine.

Keeping a changelog useful comes down to how you word each entry. Write it for the person upgrading. Here's the same change written twice:

### Fixed
- fix tz bug in utils (#482)

### Fixed
- Dates no longer shift by one day for users east of UTC (#482).

The first line describes the code. The second describes what the reader will notice, which is the whole point of a changelog. Keep one change per bullet and use the same tense throughout. If several people edit the file, agree on list markers and heading style too; our Markdown style guide covers both. The Markdown documentation guide covers how a changelog fits beside the rest of your project docs.

Try it below. Edit the entries, add a version, and watch the bracketed headings with a matching definition turn into links in the preview.

Changelog

All notable changes to this project will be documented in this file.

Unreleased

Added

  • Dark mode for the settings page.

2.0.0 - 2026-11-03

Changed

  • Breaking: The export endpoint returns JSON instead of CSV.

Fixed

  • Dates no longer shift by one day for users east of UTC.

[1.3.1] - 2026-10-14 [YANKED]

Fixed

  • Report totals now include refunded orders.
74 words562 characters24 lines
Markdown

The headings link because of the definitions at the bottom. The 1.3.1 heading has no definition, so it stays plain bracketed text, and deleting any other definition does the same to its heading.

Conventional Changelog: From Commit Messages to Entries

Tools in the conventional changelog family read commit subjects written to Conventional Commits 1.0.0 and draft the next release for you. Under that spec, fix maps to a PATCH release and feat to a MINOR release. A ! after the type, or a BREAKING CHANGE: footer, maps to MAJOR under Semantic Versioning. Other types such as docs, chore and refactor have no version effect on their own. Our Conventional Commits cheat sheet lists the types and breaking-change markers in one table.

Say these commits land after 1.3.1:

feat(export): add CSV export to the reports screen
fix(dates): stop shifting dates for users east of UTC
fix(export)!: return JSON from the export endpoint
refactor: split report builder into modules
docs: fix typo in README

A generator would propose 2.0.0 because of the !, and draft something like this:

## [2.0.0](https://github.com/example-org/example-app/compare/v1.3.1...v2.0.0) (2026-11-03)

### BREAKING CHANGES
* **export:** return JSON from the export endpoint

### Features
* **export:** add CSV export to the reports screen

### Bug Fixes
* **dates:** stop shifting dates for users east of UTC
* **export:** return JSON from the export endpoint

The breaking commit shows up twice, once as a note and once under its type. That's a usable draft, but compare it with the 2.0.0 section in the changelog example at the top of this post. The breaking entry doesn't say how to keep CSV output, and the subjects describe code, not effects. Depending on your configuration, the refactor commit can show up too. We prefer to generate the draft and then spend a few minutes rewriting it by hand.

Changelog Tools That Draft the File for You

A few established tools, each described by its own README:

  • release-please (Google) reads Conventional Commits, updates CHANGELOG.md and creates GitHub releases.
  • git-cliff generates changelogs from Git history using conventional commits or regex-based custom parsers.
  • auto-changelog builds a changelog from git tags and commit history, linking merged pull requests and closed issues.
  • standard-version is deprecated, and its README points GitHub users to release-please.

GitHub's Generate release notes button is different. It fills in a release description with merged pull requests and contributors, but it doesn't write a CHANGELOG.md in your repository.

If you'd rather not install anything, our changelog generator runs in the browser. Paste conventional-commit or git log text, and it outputs Keep a Changelog Markdown or GitHub-style release notes. It doesn't connect to your repository, so you copy the log in yourself.

Changelog Questions Developers Ask

The best changelog example to copy is the one your users can scan at a glance: dated versions, six types, breaking changes marked, and a compare link on every heading. Generate a draft if it saves time, then rewrite it for the reader. Paste your file into the editor to check the headings and links in the live preview, and download it as .md when it's ready.