Changelog Examples, Format and Template (2026)

Changelog examples teach the form faster than any style guide: read two or three good ones and the pattern is clear. A changelog is the running, dated record of what changed in a piece of software — newest first, grouped by version or by period, one line per change a user could notice. The good ones share three habits: every user-facing change is listed, changes are grouped by type so a reader can skip to what matters, and each release carries a version and a date so the record can be cited. This post gives you the definition, the standard changelog format section by section, a CHANGELOG.md template you can copy, three worked changelog examples (a command-line tool, a SaaS product page, an API), one real example generated from a week of commits, and a checklist for how to maintain a changelog once you have one.

What is a changelog?

A changelog is a file or page that lists the notable changes to a product, release by release, in reverse chronological order. It answers one question for three audiences: users who want to know what is new or different before they upgrade, integrators who need to see breaking changes and deprecations before their build fails, and your own team six months from now, trying to remember when a behaviour changed. It is a record, not an announcement — it accumulates, and nothing is deleted from it.

Where it lives depends on who reads it. A CHANGELOG.md at the root of the repository is the convention for libraries and command-line tools, because the readers are already in the repo. A hosted changelog page on the product's own site suits SaaS products whose users never open GitHub. GitHub Releases sits in between: a release page per tag, generated from merged pull-request titles, visible to anyone watching the repository — good for developers, invisible to everyone else (see GitHub Releases vs. a changelog tool).

Changelog or change log? The same thing — the one-word form is standard today. The changelog management page covers the spelling question and how a changelog differs from release notes.

The standard changelog format

The changelog format most teams converge on comes from Keep a Changelog, with version numbers from Semantic Versioning. Both are public conventions, and the parts are few:

Two rules matter more than the section names. Newest first, so the reader never scrolls to find the current release. And one entry per user-noticeable change, written for the reader — a changelog that pastes commit messages is a git log with a different filename.

A changelog template you can copy

# Changelog

All notable changes to this project are documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

## [Unreleased]

### Added
- {New capability, described as what the user can now do.}

## [1.2.0] - {YYYY-MM-DD}

### Added
- {New feature.} ({link to the pull request or docs})

### Changed
- {Existing behaviour that changed, and what to do about it.}

### Deprecated
- {Feature} is deprecated and will be removed in {version}. Use {replacement} instead.

### Fixed
- {What now works.}

### Security
- {Vulnerability fixed.} ({advisory link})

## [1.1.0] - {YYYY-MM-DD}
...

[Unreleased]: {compare URL}/v1.2.0...HEAD
[1.2.0]: {compare URL}/v1.1.0...v1.2.0

Drop the groups you do not use in a given release rather than leaving them empty, keep the order the same from version to version, and date every version — a heading that says only "v1.2.0" tells an integrator nothing about how old their dependency is.

Changelog examples

Three worked examples for the three places a changelog usually lives, then a real one. The first three are fictional and labelled as such; none of them is a Shipstar customer.

CHANGELOG.md example (Keep a Changelog style)

A fictional command-line tool, relay, that syncs environment variables between machines. Two releases, all six groups used across them:

# Changelog

## [Unreleased]

## [2.1.0] - 2026-09-02

### Added
- "relay diff" compares the local environment with a remote one and prints the keys that differ. (#412)
- Shell completions for fish, alongside the existing bash and zsh completions.

### Changed
- "relay push" now refuses to overwrite a remote value that changed since your last pull; pass --force to override. (#398)

### Fixed
- Keys whose value contains "=" are parsed correctly instead of being truncated at the first "=". (#405)

## [2.0.0] - 2026-08-12

### Changed
- **Breaking:** the config file moved from ~/.relayrc to ~/.config/relay/config.toml. Run "relay migrate-config" once to move it.

### Deprecated
- The --env-file flag is deprecated and will be removed in 3.0.0. Use --from FILE instead.

### Removed
- Support for Python 3.8, which reached end of life in October 2024.

### Security
- Values passed to "relay set" are no longer written to the shell history. (Advisory published separately.)

SaaS product changelog example

A fictional scheduling app, Slotwise, publishing a hosted changelog page by week. The entries are prose, benefit first, with the internal detail left out:

## Sep 1–7, 2026 · 2 New · 1 Improved · 1 Fixed

**New — Shared booking pages for teams.** Invite teammates to one booking page and let invitees pick any available person, or a specific one. Round-robin assignment keeps the load even.

**New — Buffer time between meetings.** Add a 5, 10 or 15 minute gap after each booking so back-to-back calls stop overlapping. Off by default; set per event type.

**Improved — Calendar changes sync in under a minute.** Edits made in Google Calendar or Outlook appear on your booking page within 60 seconds instead of the previous 15-minute polling window.

**Fixed — Time zones with half-hour offsets display correctly.** Invitees in Kolkata, Adelaide and Tehran now see slot times in their own zone.

Notice what is not there: no ticket numbers, no service names, no "refactored the sync worker". The reader is a customer, and every line says what they can now do.

API changelog example

A fictional payments API, versioned by date. Breaking changes lead, deprecations carry a sunset date, and the migration is shown rather than described:

## 2026-09-10

### Breaking changes
- The "amount" field on POST /v2/charges is now an integer in minor units (cents). Decimal strings return 400.

  Before:  "amount": "19.99"
  After:   "amount": 1999

### Deprecated
- GET /v1/charges is deprecated and will be removed on 2027-03-01. Migrate to GET /v2/charges, which paginates with a cursor instead of page numbers.

### Added
- POST /v2/refunds accepts an Idempotency-Key header. Repeating a request with the same key within 24 hours returns the original response.

### Fixed
- Webhook retries back off exponentially (1, 2, 4, 8 minutes) instead of retrying every minute for an hour.

A real, generated changelog example

The one real example here is Shipstar's own changelog, which the product generates from the repository's commits every week and publishes at shipstar.ai/changelog. This is the period Aug 21–28, 2026 as published — 4 New, 3 Improved, 1 Fixed, with the provenance line the page carries: "Generated by Shipstar from 77 commits." Two of its eight entries, as they appear:

[New] Server-rendered changelog pages with permalinks, RSS feed, and social cards (2026-08-24) — Your changelog is now a fully crawlable, SEO-friendly page with a permanent URL for every release period, an RSS feed, and auto-generated Open Graph social cards — so crawlers, AI answer engines, and social platforms all see your release content instead of a blank widget.

[Fixed] Auto-published changelogs were stuck on "Loading entries" on the public page (2026-08-23) — Content published automatically never received a public slug, so the public changelog page couldn't resolve it and displayed a permanent loading spinner. Auto-published changelogs now get a slug assigned at publish time, and the page falls back gracefully to inline entries if a slug is unavailable.

Nobody typed those. They were written from the week's commits and pull requests, reviewed, and published — in the same shape as the fictional SaaS example above, because that is the shape a reader needs.

Where to read more real changelogs

Three public changelogs worth studying for format alone, one per style: GitHub's changelog is a hosted page of dated, one-topic entries grouped by month, newest first; Tailwind CSS's CHANGELOG.md is a single long-running file kept in the repository, thousands of lines deep, that shows how the file form scales; and Node.js's CHANGELOG.md is an index over one changelog file per release line — how a project with several supported versions keeps the record navigable.

How to maintain a changelog?

The hard part of a changelog is not the format, it is keeping it current. How to keep a changelog that stays true:

1. Add the entry when the change merges, not when you release. That is what the Unreleased section is for; a release then becomes a rename.
2. One line per user-noticeable change. Internal refactors, dependency bumps and test fixes do not belong unless a user could tell.
3. Group by type — Added, Changed, Deprecated, Removed, Fixed, Security — so a reader scanning for breaking changes finds them.
4. Newest first, always.
5. A version and an ISO date on every release heading.
6. Write for the reader: say what they can do now or what will stop working, and never paste the commit message.
7. Link each line to the pull request, issue or documentation that holds the detail.
8. Put breaking changes and deprecations first within a release, and give every deprecation a removal version or date.
9. Keep one voice across releases, whoever wrote the entry.
10. Publish it where your users look — a page on your site, an email, a feed — not only in the repository.

Automation exists for the mechanical half. git-cliff, conventional-changelog and GitHub's "Generate release notes" button will roll commit or pull-request titles into a changelog file or a release page for you, provided your commits follow a convention such as Conventional Commits. What they produce is a grouped list of titles — the git log in a better order. An AI generator takes the other half: it reads ordinary commits and pull-request descriptions and writes the user-facing line, which is the step people skip when a changelog goes stale. The GitHub changelog generator page walks through generating a changelog from GitHub commits and pull requests without a commit convention.

Changelog vs release notes: a changelog is the running record; release notes announce one release and are written to be read once. The two come from the same commits, and most teams need both. The format, a template and examples for that side are in Release Notes Examples, Format and Template; if you ship from GitHub and wonder whether GitHub Releases alone is enough, read GitHub Releases vs. a changelog tool.

Generate the changelog instead of writing it

Every example above was either written by hand or generated from commits — and only the generated one keeps itself current. Shipstar connects to a GitHub repository, reads the commits and merged pull requests for a period, and writes the changelog entry in this format, in your project's voice. The draft lands in a review queue; on approval it publishes to a hosted changelog page with a permanent URL per period, an embeddable widget for your own site, and an RSS feed — and the same commits can produce the week's release notes, social posts and newsletter. Shipstar is a hosted service, not an open-source tool; the Free plan is the no-cost entry: $0, no card, one project, 1,000 credits a month. A public changelog generation costs 100 credits, so roughly ten a month are free; Solo is $25/month or $240/year for 50,000 credits. GitHub is the only source today.

Read how the changelog management tool compares with the alternatives, see the automated changelogs content type, browse Shipstar's own generated changelog, or connect a repository free and compare the first draft with your CHANGELOG.md.