Changelog examples: 8 changelogs for libraries, apps, APIs and docs

A changelog is a file or page that lists the notable changes in each version of a project, newest first, with the release date of every version. Many projects follow the Keep a Changelog format, which groups each version's changes under six headings: Added, Changed, Deprecated, Removed, Fixed and Security. The eight changelog examples below cover different kinds of project, from an open-source library's CHANGELOG.md to a product updates page and an API changelog with shut-off dates, and each is followed by notes on why it works.

The projects are invented, so every entry can be copied and adapted. If you need the friendlier version of one release for users, with highlights and upgrade notes, start from the release notes template instead.

The Keep a Changelog format

Keep a Changelog, created and maintained by Olivier Lacan, is a short set of conventions for a CHANGELOG.md file. Version 1.1.0 defines a changelog as a curated, chronologically ordered list of notable changes for each version of a project. Its first principle is “Changelogs are for humans, not machines.” The others: every version gets an entry, changes of the same type are grouped, versions and sections can be linked to, the latest version comes first, each version shows its release date, and the file says whether the project follows semantic versioning.

Three more conventions do most of the work. An Unreleased section at the top collects changes as they are merged, so a release only needs a new heading. Dates are written YYYY-MM-DD, which can't be misread the way 04/05/2026 can. And a yanked release, one pulled for a serious bug or security problem, stays in the file with [YANKED] after its date. The file is called CHANGELOG.md; Keep a Changelog notes that some projects use HISTORY, NEWS or RELEASES, and argues for one consistent name so people can find it.

Semantic versioning in brief

Semantic Versioning 2.0.0, originally written by Tom Preston-Werner, gives each part of a MAJOR.MINOR.PATCH number a meaning, so the number alone tells readers how careful to be with an upgrade.

• 0.y.z is for initial development. Anything may change at any time, and 1.0.0 defines the public API. Flag breaking changes in a 0.x changelog anyway.
• Pre-releases and builds have their own marks. A hyphen starts a pre-release label (1.0.0-alpha) and a plus sign starts build metadata (1.0.0+20130313144700).
• “v1.2.3” is a tag name. The semantic version is 1.2.3, so write version headings without the v.
• A released version never changes. If a minor release broke compatibility by mistake, SemVer's FAQ says to fix it in a new minor release that restores compatibility, and the changelog should say so.

Open-source library CHANGELOG.md example

A library's readers are developers deciding whether an upgrade is safe. Here is a complete CHANGELOG.md for mdbinder, an invented tool that turns a folder of Markdown chapters into an EPUB file.

# Changelog

All notable changes to mdbinder are documented in this file.

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

## [Unreleased]

### Added
- `--cover` option to set the cover image from the command line.

## [3.0.0] - 2026-10-02

### Removed
- **Breaking:** EPUB 2 output. mdbinder now writes EPUB 3 only. If you
  need EPUB 2, stay on 2.x, which gets security fixes until 2027-04-01.
- **Breaking:** the `book.toml` config file, deprecated in 2.4.0.
  Run `mdbinder migrate-config` to convert it to `book.yaml`.

### Changed
- Chapters are ordered by the number at the start of the file name
  (`01-arrival.md`), not alphabetically. Files without a number go last.

### Fixed
- Footnotes inside block quotes keep their back-links (#214).

## [2.4.0] - 2026-07-15

### Added
- `toc_depth` setting in `book.yaml` for the table of contents.

### Deprecated
- `book.toml`. It still works in 2.x and will be removed in 3.0.0.

## [2.3.1] - 2026-06-03

### Fixed
- Curly quotes in chapter titles are no longer straightened in the
  table of contents (#198).

[unreleased]: https://example.com/mdbinder/compare/v3.0.0...HEAD
[3.0.0]: https://example.com/mdbinder/compare/v2.4.0...v3.0.0
[2.4.0]: https://example.com/mdbinder/compare/v2.3.1...v2.4.0
[2.3.1]: https://example.com/mdbinder/compare/v2.3.0...v2.3.1

Why it works. The header says which format and which versioning scheme the file follows, as Keep a Changelog asks. The 3.0.0 entry leads with its two breaking changes and says what to do about each, and the config file was deprecated one minor version earlier, in 2.4.0, the order SemVer's FAQ recommends. Issue numbers stay because these readers will click them, and the link references at the bottom turn every version heading into a link to its diff.

Command-line tool with yanked release

A tool people pin to a version needs the uncomfortable entries most: the release that was pulled and the security fix that replaced it.

Why it works. The yanked version stays in the file, marked the way Keep a Changelog recommends, with the reason and the version to use instead, so anyone who pinned 1.9.0 can see why it is no longer offered. Security comes first in 1.9.1 and tells readers what to do, not only what changed. The Changed line names the cost of the new default and how to opt out.

Web app product updates page

Nobody installs a version of a web app, so a product changelog is organized by date. Its readers are customers, not developers.

Why it works. Each headline names the change and the date follows it, because readers scan the page for what is new, not for a day. Each entry starts with what the reader can now do and points to the help article. The quiet fortnight still gets its one line, which tells customers the product is looked after. And “You confirm each suggestion” answers the question a journalist would ask before trusting the feature with a source's name.

Mobile app store changelog

Store notes are read in a list of other updates, on a small screen. Three lines are plenty.

Why it works. The change most people will notice comes first and says where to find it. The text doesn't open with “What's new in 4.2”: the store already shows the version number, and the first line is the one a reader sees before deciding to read on. There is no “bug fixes and performance improvements” line, which tells the reader nothing. The full changelog on the app's website, under the same version number, carries the detail.

API changelog with deprecations

Integrators read an API changelog to answer one question: will my code break, and when? Every entry says which versions it affects.

Why it works. The breaking change says exactly what to send to keep the old behavior. The deprecation names the replacement, the shut-off date and the migration guide, and the API repeats the warning in its responses: the Deprecation header (RFC 9745, March 2025) marks a resource as deprecated, and the Sunset header (RFC 8594, May 2019) gives the date it is expected to stop responding. Several public APIs name versions by date. Stripe's sample requests send a Stripe-Version header that starts with a date, and GitHub's send an X-GitHub-Api-Version date. The technical writing examples show how the rest of a developer docs set fits around it.

Internal platform changelog

Inside a company, the readers are other engineering teams, and they want to know whether they have to do anything.

Why it works. The split answers the reader's only question before any detail. The action has a date, the exact line to change and the names of the teams still affected. The improvement comes with a before-and-after number instead of an adjective.

Game patch notes example

Patch notes are a changelog for an audience that reads every number. Balance changes show the old value and the new one.

Why it works. Old → new values let players judge each change for themselves. The designer's note gives the reason for the most disputed change, which players would otherwise guess at. Known issues come with the planned fix, so nobody reports them again.

Style guide revision log

Documents change too. A style guide needs a changelog more than most, because editors apply its rules from memory and need to know when one moved.

Why it works. Each change records the old rule as well as the new one, so a copy editor can tell an older story from a mistake. The last line says when the edition takes effect and that the archive stays as it is. The same log works for an SOP library (see the SOP examples, each of which ends with a revision line) and for a book's style sheet.

Changelog vs release notes

The two often start from the same change, but they serve different readers. Here is the widget fix from the Tidewatch store text above, written once for each:

Put the issue number in the store text and no user can do anything with it. Leave the mechanism out of the changelog and the next developer can't tell what changed, or whether a later bug is the same one coming back. Keep one source of changes and write both versions from it, so the two never disagree about what shipped.

How to write changelog entries

• Start from what changed for the reader. Use the names on the screen or in the API, not the names of internal modules.
• One change per line, breaking changes first. Mark them “Breaking” even under Removed or Changed, so readers scanning for the word find it.
• Say what to do. A deprecation names its replacement and its removal version or date. A breaking change gives the migration step or links to it.
• Use numbers instead of adjectives. “Builds take 6 minutes instead of 10” beats “much faster builds”.
• Write the entry when the change merges. Add a line under Unreleased in the same pull request. Reconstructing a month of changes on release day is when entries go missing.

If you keep the changelog in Strokes, ask the Strokes Assistant to review a new entry against the rest of the file. It flags inconsistencies such as a version without a date, a breaking change filed under Fixed or a deprecation with no removal date.

Building a changelog from commits

Conventional Commits 1.0.0 calls itself “a lightweight convention on top of commit messages”. Each message starts with a type: fix commits map to PATCH releases, feat commits to MINOR releases, and a BREAKING CHANGE footer or a ! after the type to MAJOR. Its site lists automatic changelogs among the reasons to adopt it, and release tools can turn such a history into a sorted draft.

feat!: drop EPUB 2 output
fix: keep footnote back-links inside block quotes (#214)
refactor: split the parser into two modules
chore(deps): bump yaml to 2.6.1
feat!: remove support for book.toml

From those five commits, three lines reach the 3.0.0 entry in the file above: two breaking entries under Removed (EPUB 2 and book.toml) and one under Fixed (the footnotes). The ! marks are also what make the next version 3.0.0. The refactor and the dependency bump disappear, because nothing changed for the reader. That editing step is the point. Keep a Changelog's warning still holds: commit logs are full of noise, because a commit records a step in the work, while a changelog entry records a difference someone will notice.

Common changelog mistakes

• Leaving out the awkward parts. Keep a Changelog warns that a changelog mentioning only some changes can be as dangerous as none. Deprecations, removals and breaking changes are the lines people most need.
• Dates people can misread. 04/05/2026 is April in the US and May in most of Europe. Use 2026-04-05.
• Deleting a bad release. Mark it [YANKED], say why and point to the replacement.
• A version number that contradicts the entry. A “Breaking” line under a PATCH release tells users the number can't be trusted.
• Internal shorthand in a public changelog. Code names and team names mean nothing to customers.