Changelog Format: Standards, Conventions & Examples

A changelog is only useful if people can read it at a glance. That's what a good changelog format buys you: a predictable structure so any reader can find what they need without hunting.

Changelog vs. release notes: a quick reminder

Same event, different framing:

A changelog is the complete, chronological record of what changed — terse, technical, for people who want precision.
Release notes are the curated story of what it means — benefit-led, for people who just use the product.

Many teams keep both. This article is about the changelog: the format and conventions that make it dependable.

The "Keep a Changelog" standard

The most widely-adopted convention is Keep a Changelog, and it's worth following because your readers likely already know it. Its core principles:

Changelogs are for humans, not machines. Write entries a person can understand, not raw diffs.
Every version gets its own section, newest at the top.
Group changes by type using a standard set of categories.
Date every release in ISO format (YYYY-MM-DD).
Keep an Unreleased section at the top to collect changes as you go.

The standard categories

Category	Use for
Added	New features
Changed	Changes to existing functionality
Deprecated	Soon-to-be-removed features
Removed	Features taken out
Fixed	Bug fixes
Security	Vulnerability patches

Using a consistent set means readers learn where to look — breaking changes live under Changed or Removed, fixes under Fixed, and so on.

Semantic Versioning in one minute

Changelog format and version numbers go together. Semantic Versioning (SemVer) gives each release a MAJOR.MINOR.PATCH number where each part has meaning:

MAJOR (2.0.0) — incompatible / breaking changes
MINOR (1.3.0) — new functionality, backward-compatible
PATCH (1.2.4) — backward-compatible bug fixes

The payoff: a reader can tell from the number alone whether an upgrade is risky. A jump to 2.0.0 says "read the notes carefully." A move to 1.4.3 says "safe patch."

A complete changelog example (Markdown)

# Changelog All notable changes to this project are documented here. This project adheres to Semantic Versioning. ## [Unreleased] ### Added - Webhook support for the `invoices` resource. ## [2.1.0] — 2026-07-05 ### Added - Dark mode across the dashboard. - CSV export for the reports page. ### Changed - Export performance improved ~3× for large datasets. ### Fixed - Calendar sync no longer offsets events by the wrong time zone. ## [2.0.0] — 2026-06-12 ### Changed (breaking) - Renamed the `user_id` field to `account_id` across all endpoints. ### Removed - Dropped the deprecated v1 authentication flow.

Notice the discipline: newest first, dated, grouped, and breaking changes flagged loudly. For the user-facing version of the same release, see our release notes templates.

Changelog format for APIs (structured / JSON)

If your changelog feeds tooling as well as humans, a structured format helps:

{ "version": "2.1.0", "date": "2026-07-05", "changes": { "added": ["Dark mode across the dashboard", "CSV export on reports"], "changed": ["Export performance improved ~3× for large datasets"], "fixed": ["Calendar sync time-zone offset"] } }

Tip: maintain the human-readable Markdown as the source of truth and generate the JSON from it, not the other way around — readability first.

Formatting conventions worth adopting

Link version numbers to a diff or release page so readers can dig in.
Reference issues/PRs where useful (#1234) for traceability.
Pick one tense — imperative or past — and stay consistent.
Flag breaking changes visibly. Never make readers infer them.
Keep an Unreleased section so nothing gets lost between releases.

Generating a formatted changelog automatically

Maintaining this structure by hand is disciplined work — and the exact kind of repetitive task that's easy to let slip when you're shipping fast.

Because the conventions are so regular, they're a natural fit for automation. An AI release notes generator can read your commits, sort them into Added / Changed / Fixed, apply your version number, and produce a formatted entry you just review. ChangeNote does this straight from your GitHub history.