What is a changelog template?

A changelog template is a reusable structure for the running record of changes to your product — typically a versioned, reverse-chronological document with dated entries grouped into change types like Added, Changed, Fixed, and Removed. It's a file or page structure, not announcement copy. The most widely used convention is the Keep a Changelog format: a single CHANGELOG.md with one section per version and up to six change-type categories per section.

What's the difference between a changelog template and a release notes template?

A changelog template structures the running record: every version, every change, in a consistent categorized format, often technical. A release notes template structures a single announcement: one release, written narratively for end users, distributed by email, in-app, or on a launch page. You usually need both — the changelog is the source of truth, the release notes are the broadcast. This post covers the record; our release notes templates page covers the announcements.

What format should a changelog file use?

The de facto standard is Keep a Changelog: a Markdown file named CHANGELOG.md at the repo root, one section per version with an ISO 8601 date (YYYY-MM-DD), changes grouped under Added, Changed, Deprecated, Removed, Fixed, and Security, plus an Unreleased section at the top for merged-but-unshipped work. Pair it with Semantic Versioning so version numbers carry meaning.

How do I keep a changelog updated automatically?

Two proven paths. Conventional Commits plus a generator turns structured commit messages (feat:, fix:, BREAKING CHANGE:) into changelog sections mechanically — free, but the output reads like commits. AI-based tools like ReleasePad read the actual commits and pull requests between releases and draft human-readable entries you review and publish. Either way, the fix is the same: stop transcribing work you already recorded in git.

Where should a changelog live — in the repo or on a public page?

Both, serving different readers. A CHANGELOG.md in the repo serves developers and tooling, and stays version-controlled with the code. A public changelog page serves your users — and increasingly AI assistants answering questions about your product — with categories, search, and an in-app widget. Developer tools can sometimes get away with repo-only; SaaS products with non-technical users can't.

Changelog Template: 5 Copy-Paste Formats

Five changelog templates you can copy today — the standard CHANGELOG.md, a conventional-commits variant, a SaaS changelog page entry, an internal one, and an AI-readable structure — plus the conventions that keep any of them from rotting.

A changelog template and a release notes template are not the same thing, even though search engines blur them. Release notes are the announcement — one release, written for humans, sent once. The changelog is the record — every version, every change, structured the same way, forever. If what you actually want is announcement copy (email blasts, App Store “What’s New” text, launch posts), that lives in our release notes templates page. This post is about the record.

The record is the harder one to keep. An announcement gets written in a burst of launch energy; the changelog needs the same structure applied on a random Tuesday for a two-line bug fix. That’s why the template matters more here — the less thinking an entry requires, the more likely it gets written. (Most teams that abandon their changelog don’t decide to stop; they just skip one release, then two.)

Here are five templates, ordered from “repo file” to “public product changelog,” with notes on when each fits.

1. The Standard CHANGELOG.md (Keep a Changelog Style)

The default answer. One Markdown file at the repo root, reverse chronological, one section per version, changes grouped into up to six categories. This is the Keep a Changelog convention — the closest thing the industry has to a standard, revised in June 2026 (v2.0.0) with explicit guidance for LLM consumption.

# Changelog

All notable changes to this project are documented in this file.

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

## [Unreleased]

### Added
- (Merged but unreleased work goes here, then moves down on release day.)

## [2.1.0] - 2026-07-17

### Added
- Bulk CSV export on the reports page.

### Changed
- Dashboard charts now load lazily; initial paint is noticeably faster.

### Deprecated
- The v1 reports endpoint. Removal planned for 3.0.0 — migrate to v2.

### Fixed
- Sessions no longer expire early when "remember me" is checked.

### Security
- Upgraded the JWT dependency to patch a token-validation vulnerability.

## [2.0.0] - 2026-06-30

### Removed
- Legacy XML export (deprecated since 1.8.0).

[Unreleased]: https://github.com/you/app/compare/v2.1.0...HEAD
[2.1.0]: https://github.com/you/app/compare/v2.0.0...v2.1.0
[2.0.0]: https://github.com/you/app/compare/v1.8.0...v2.0.0

The rules that make it work: the six change types are Added, Changed, Deprecated, Removed, Fixed, Security — use only the ones a release needs, in that order. Dates are ISO 8601 (YYYY-MM-DD), always. The Unreleased section at the top collects merged work so release day is a cut-and-relabel, not an archaeology dig. The link references at the bottom give every version a diff URL.

Use it when: you’re a developer tool, an open source project, or any team whose changelog readers are comfortable in a repo.

2. The Conventional-Commits Variant (Generated, Not Written)

If your team writes Conventional Commits, the changelog can be generated instead of written. The template here is really two templates — the commit format going in, and the changelog shape coming out.

The input, enforced at commit time:

feat(reports): add bulk CSV export
fix(auth): honor "remember me" on session refresh
perf(dashboard): lazy-load charts
feat(api)!: switch created_at to ISO 8601

BREAKING CHANGE: created_at was a Unix timestamp, now ISO 8601.

The output, produced by a generator (release-please, semantic-release, git-cliff, and friends):

## [2.1.0] - 2026-07-17

### ⚠ BREAKING CHANGES
- **api:** created_at was a Unix timestamp, now ISO 8601.

### Features
- **reports:** add bulk CSV export
- **auth:** honor "remember me" on session refresh

### Performance
- **dashboard:** lazy-load charts

The trade: zero manual changelog work, perfect consistency — and output that reads exactly like what it is: commit messages. Fine for a developer audience; rough for end users, because fix(auth): honor "remember me" on session refresh describes the code, not the benefit. Our comparison of automation methods covers where this approach tops out.

Use it when: commit discipline exists (or is enforceable) and your changelog readers are developers.

3. The SaaS Changelog Page Entry (User-Facing)

A public SaaS changelog is a different animal: entries are dated but often unversioned, categorized with labels instead of change types, and written for users who don’t know or care what a semver bump means. The template is per-entry:

## Bulk CSV export for reports
2026-07-17 · New feature · Reports

**What's new**
Every report now has an Export button that produces a CSV of
exactly what's on screen — filters, date ranges, and custom
columns included.

**Why it matters**
The old workaround was screenshots or copy-pasting tables into
a spreadsheet. Finance teams asked for this more than any other
export format.

**How to try it**
Open any report → Export → CSV. Available on all plans.

The anatomy: a headline that names the benefit (not “v2.1.0”), a date, a category label users can filter by (New feature, Improvement, Fix), then three short blocks — what, why, how. The what/why/how discipline is what separates changelogs users actually read from commit dumps with a nicer font. Cap it at three paragraphs; anything longer belongs in a blog post the entry links to.

Use it when: your changelog is a product surface — a public page and an in-app widget — and its readers include non-developers.

4. The Internal Changelog Entry (Team-Facing)

Internal and external changelogs serve different audiences, and the internal one has its own template: it’s for support, sales, and future-you, so it records the operational context the public entry deliberately omits.

## 2026-07-17 — Deploy #412

**Shipped**
- Bulk CSV export (reports) — public entry published
- Session-refresh fix for "remember me"

**Behind a flag**
- New onboarding flow at 10% rollout (`onboarding_v3`)

**Support notes**
- CSV export caps at 50k rows; larger reports queue an email
  delivery instead. Expect "where's my file" tickets.

**Watch**
- Dashboard p95 load time (lazy-loading change)

**Owner:** @felix

Use it when: more than two people need to know what shipped — which, in practice, is the moment you have a support inbox.

5. The AI-Readable Changelog (Structure for Machines)

New requirement, increasingly non-optional: AI assistants and coding agents read changelogs to answer “what changed” questions about your product — and they read structure, not vibes. The template here is a set of constraints layered onto whichever format above you use:

# Changelog — YourApp

## 2026-07-17 — Bulk CSV export for reports
Type: New feature
Area: Reports

Every report now exports to CSV with filters and custom columns
applied. Available on all plans. Docs:
https://yourapp.com/docs/reports/export

## 2026-07-10 — created_at is now ISO 8601 (breaking, API v3)
Type: Breaking change
Area: API

created_at fields switched from Unix timestamps to ISO 8601
strings. Migration guide:
https://yourapp.com/docs/api/v3-migration

The constraints that matter: identical heading structure on every entry (parsers reward consistency), ISO dates, one entry per change (not “misc improvements”), explicit Type: and Area: fields, absolute URLs, and a plain-Markdown version of the whole feed that doesn’t require executing JavaScript to read. Then point to it from your llms.txt so AI tools can find it.

Use it when: your users’ AI tools are answering questions about your product — which, if you sell to developers, is already happening.

The Conventions That Keep Any Template Alive

Whichever template you pick, the failure modes are the same five:

Forward chronology. Newest entry first, always. A changelog that opens with 2023 reads as abandoned even when it isn’t.
Vague entries. “Bug fixes and improvements” is the entry users learned to ignore. If it was worth shipping, it’s worth one specific sentence.
Inconsistent dates. Pick ISO 8601 and never deviate — humans parse it fine and machines parse it perfectly.
Mixed audiences in one entry. The moment you’re explaining a database migration to end users, split into internal + external (templates 3 and 4).
The skipped week. The template’s real job is making entries cheap enough that “I’ll do it later” never starts. If entries still aren’t happening, the problem isn’t the template — it’s that a human is transcribing information that already exists in git.

That last one has a structural fix. ReleasePad connects to your GitHub repository, reads the commits and PRs between releases, and AI-drafts entries in the user-facing shape of template 3 — with the machine-readable output of template 5 generated automatically. You review, edit, publish. The template stops being a discipline problem and becomes a review step.

Which Template Should You Start With?

Open source or dev tool → Template 1, in the repo. Add template 2’s generation when commit discipline allows.
SaaS with non-technical users → Template 3 on a public page, template 4 internally.
API product → Template 1 or 2 for the record, plus explicit breaking-change entries (see our API release notes guide).
Anyone whose users use AI tools → whichever of the above, with template 5’s constraints applied.

Copy them, adapt the labels to your product, and delete the sections you don’t need. A changelog template only has one success metric: whether the entry after this one gets written.

The Changelog Template Pack: 5 Copy-Paste Formats