Changelog templates for every kind of project

Q: What should a CHANGELOG.md look like?

Start with a # Changelog heading and a short preamble naming the format and versioning scheme. Then an ## [Unreleased] section, then one section per version such as ## [1.4.0] - 2026-11-03, newest first, with changes under Added, Changed, Deprecated, Removed, Fixed and Security. Reference links at the bottom point each version at its diff. That's the Keep a Changelog 2.0.0 format, shown in template 2.

Q: How do I record breaking changes in a changelog?

Mark them **Breaking:** on the entry, under Changed or Removed, rather than in a separate section, and add a one-line upgrade step. If you follow Semantic Versioning, they go in a major version. Announce them in your release notes too. How to document breaking changes covers what to write.

A changelog is the running record of every notable change, newest first. These five templates cover a plain Markdown file, the Keep a Changelog format, a customer-facing product changelog, an open-source library's CHANGELOG.md and a mobile app's version history, each with a short filled-in example.

Updated 13 November 2026Facts checked 13 November 20265 templates with filled-in examples

Free tool · no sign-up

Start your changelog from your merged pull requests

Paste a public GitHub repository and get what changed since your last tag as a Keep a Changelog section, breaking changes marked, ready to edit into your CHANGELOG.md. Free, no sign-up, no AI.

On every release, automatically:uses: kalmwerk/release-notes-action@v1Free GitHub Action

The short answer

A changelog lists the notable changes of every version, newest first, each with its version number and date. Release notes announce one release: see the release notes templates.
For code, name the file CHANGELOG.md, keep an Unreleased section at the top and group changes under Added, Changed, Deprecated, Removed, Fixed and Security, as Keep a Changelog 2.0.0 recommends.
Mark breaking changes **Breaking:** on the entry itself, and always record deprecations and removals.
For customers, a dated product changelog with New, Improved and Fixed labels reads better than version numbers.
Don't paste a git log: keep the changes people notice, written for them. A draft from your merged pull requests is a fine place to start.

Which template should you use?

Pick by who reads the changelog and where it lives. A product with an app and an API often keeps two: a CHANGELOG.md for developers and a product changelog for customers.

Plain Markdown
Use it for
A first changelog, small projects, internal tools
Written for
Your team and early users
Where it lives
CHANGELOG.md or a docs page
Ordered by
Version or date, newest first
Keep a Changelog
Use it for
Any versioned software that wants the common format
Written for
Developers, tools and coding agents
Where it lives
CHANGELOG.md in the repository
Ordered by
Version, newest first, with Unreleased on top
SaaS product changelog
Use it for
Hosted products that ship continuously
Written for
Customers and admins
Where it lives
A hosted changelog page and in-app widget
Ordered by
Date, newest first
Open-source library
Use it for
Packages on npm, PyPI, crates.io and the like
Written for
People upgrading, contributors and coding agents
Where it lives
CHANGELOG.md, mirrored to GitHub releases
Ordered by
Semantic version, newest first
Mobile app version history
Use it for
iOS and Android apps
Written for
Your team, support and app store readers
Where it lives
A file in the repository that the store text comes from
Ordered by
App version and build, newest first

Template	Use it for	Written for	Where it lives	Ordered by
Plain Markdown	A first changelog, small projects, internal tools	Your team and early users	CHANGELOG.md or a docs page	Version or date, newest first
Keep a Changelog	Any versioned software that wants the common format	Developers, tools and coding agents	CHANGELOG.md in the repository	Version, newest first, with Unreleased on top
SaaS product changelog	Hosted products that ship continuously	Customers and admins	A hosted changelog page and in-app widget	Date, newest first
Open-source library	Packages on npm, PyPI, crates.io and the like	People upgrading, contributors and coding agents	CHANGELOG.md, mirrored to GitHub releases	Semantic version, newest first
Mobile app version history	iOS and Android apps	Your team, support and app store readers	A file in the repository that the store text comes from	App version and build, newest first

Template 1 of 5

Simple Markdown changelog template

Best for: A first changelog, small projects and internal tools that don't need a formal standard.

The lightest format that still works: one heading per version with its date, newest at the top, and a short list of what changed. Start today and record changes from now on; you don't have to reconstruct the past first.

CHANGELOG.md · template

# Changelog

## [version] (YYYY-MM-DD)
- [What changed, in one line people understand]
- [Another change]
- Fixed: [the bug people hit]

## [previous version] (YYYY-MM-DD)
- [...]

Filled in: an internal reporting tool

CHANGELOG.md · example

# Changelog

## 1.3.0 (2026-11-03)
- Reports can be exported as PDF from the Share menu.
- The dashboard remembers the date range you picked last.
- Fixed: totals no longer double-count refunded orders.

## 1.2.1 (2026-10-20)
- Fixed: sign-in links expired after 5 minutes instead of 24 hours.

## 1.2.0 (2026-10-06)
- New "Team" filter on every report.
- The old CSV importer is gone; use Import → Spreadsheet.

Why it works

Newest version first, so readers see the latest change without scrolling.
YYYY-MM-DD dates sort correctly and can't be misread in another country.
When the project grows, switch to Keep a Changelog: the same file, with change types and diff links added.

Template 2 of 5

Keep a Changelog template (CHANGELOG.md)

Best for: Any versioned software that wants the format most developers and changelog tools recognise.

The whole file in the Keep a Changelog 2.0.0 format: a fixed preamble, an Unreleased section that collects upcoming changes, one section per version with its date, the six change types, and reference links at the bottom that point each version at its diff. On release day, rename Unreleased to the new version in its heading and its link, then add a fresh Unreleased section.

CHANGELOG.md · template

# 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]

## [X.Y.Z] - YYYY-MM-DD

### Added
- [New feature]

### Changed
- [Change to existing behavior; mark breaking ones **Breaking:**]

### Deprecated
- [Feature that will be removed, its replacement and the removal version]

### Removed
- [Feature removed in this version]

### Fixed
- [Bug fix]

### Security
- [CVE-YYYY-NNNNN]: [the vulnerability that was fixed]

[Unreleased]: https://github.com/OWNER/REPO/compare/vX.Y.Z...HEAD
[X.Y.Z]: https://github.com/OWNER/REPO/compare/vPREVIOUS...vX.Y.Z

Filled in: a small command-line tool, three versions

CHANGELOG.md · example

# 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
- `skylog tail --since` accepts durations like `15m` and `2h`.

## [1.4.0] - 2026-11-03

### Added
- `--json` output for `skylog status` ([#88]).

### Deprecated
- `--format=raw`: use `--json` instead. It will be removed in 2.0.0.

### Fixed
- `skylog status` exits with code 1 when the server is unreachable ([#90]).

## [1.3.1] - 2026-10-14

### Security
- Config files written by `skylog init` could be read by other users on the same machine. They are now created with owner-only permissions (0600).

## [1.3.0] - 2026-09-30

### Added
- `skylog init` creates a starter config file.

[Unreleased]: https://github.com/acme/skylog/compare/v1.4.0...HEAD
[1.4.0]: https://github.com/acme/skylog/compare/v1.3.1...v1.4.0
[1.3.1]: https://github.com/acme/skylog/compare/v1.3.0...v1.3.1
[1.3.0]: https://github.com/acme/skylog/releases/tag/v1.3.0
[#88]: https://github.com/acme/skylog/pull/88
[#90]: https://github.com/acme/skylog/pull/90

Why it works

The preamble pins the Keep a Changelog version and names the versioning scheme, so readers and tools know what to expect.
The deprecation in 1.4.0 says which version removes the flag, one major version ahead of the removal.
A Security entry leads with its CVE identifier when there is one, so security tools can match it to the advisory.
Coding agents and the free changelog-to-JSON converter read this format reliably, versions, breaking changes and deprecations included.

Free GitHub Action · no sign-up

Turn each version section into a GitHub release

Tag a release and the free GitHub Action copies that version's section from CHANGELOG.md into the GitHub release, so your changelog stays the source and nothing is written twice. One workflow step, no LogPulse account.

.github/workflows/release-notes.yml

name: Release notes

on:
  release:
    types: [published]

permissions:
  contents: write

jobs:
  notes:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: kalmwerk/release-notes-action@v1

View on GitHub Setup and options

On GitHub now; Marketplace listing coming soon: releases. Rather keep a copy in your repository? Download 1.0.3 (28 KB). On GitLab? Use the CI/CD component

No CHANGELOG.md yet? See the notes your merged pull requests give first: generate release notes from GitHub, free and with nothing to install.

Template 3 of 5

SaaS product changelog template

Best for: Hosted products that ship continuously and want a public changelog customers actually read.

Customers browse a product changelog by date, not by version. Each entry is one change with a label, so people can scan for what affects them, and month headings keep a long page easy to navigate. New, Improved and Fixed are the usual labels; they map onto Keep a Changelog's Added, Changed and Fixed.

changelog.md · template

# What's new in [Product]

## [Month YYYY]

### [Benefit-led title]
**[New | Improved | Fixed]** · [D Month YYYY]

[One or two sentences: what changed and why it matters.] [Where to find it.]

### [Benefit-led title]
**[New | Improved | Fixed]** · [D Month YYYY]

[...]

## [Previous month YYYY]

[...]

Filled in: two months of an invoicing app

changelog.md · example

# What's new in Ledgerly

## November 2026

### Send invoices on a schedule
**New** · 3 November 2026

Set an invoice to repeat weekly, monthly or quarterly from **More → Repeat**. Available on all paid plans.

### Faster search across clients
**Improved** · 3 November 2026

Search now matches company names, contact names and invoice numbers as you type.

## October 2026

### PDF totals match the invoice again
**Fixed** · 28 October 2026

Invoices with a discount and tax on the same line showed the wrong total in the PDF. Download affected PDFs again to get the corrected version.

Why it works

Month headings let people jump back to when they last looked.
The fix says what people need to do about the past (download the PDF again), not just that it's fixed.
With LogPulse the same entries feed your in-app widget, your hosted changelog and a JSON feed, so each update is written once.

Template 4 of 5

Open-source library changelog template

Best for: Packages people install and upgrade: libraries, CLIs and SDKs on npm, PyPI, crates.io and similar registries.

The Keep a Changelog format, tuned for a library whose users often jump several versions at once: a summary that counts the breaking changes on a major version, runtime requirements recorded as breaking changes, contributors credited, and a [YANKED] marker for a release that was pulled. Coding agents read this file to work out what to change when they upgrade your package.

CHANGELOG.md · template

## [Unreleased]

## [X.0.0] - YYYY-MM-DD

[Summary: how many breaking changes there are and what they are.] Migration guide: [link]

### Changed
- **Breaking:** [Old behavior → new behavior.] [The one-line upgrade step.]
- **Breaking:** Requires [runtime] [version] or later.

### Removed
- **Breaking:** [API], deprecated since [version]. Use [replacement].

### Fixed
- [Bug fix] ([#PR]). Thanks @[contributor].

## [X.Y.Z] - YYYY-MM-DD [YANKED]

[Why it was pulled, and which version to use instead.]

Filled in: a JavaScript library's major release

CHANGELOG.md · example

## [Unreleased]

## [4.0.0] - 2026-11-03

Two breaking changes: Node.js 20 or later is required, and `parse()` returns a result object. Migration guide: https://example.com/docs/upgrade-to-4

### Added
- `parseStream()` parses large files without loading them into memory ([#318]).

### Changed
- **Breaking:** Node.js 20 or later is required. Projects on Node.js 18 can stay on 3.x.
- **Breaking:** `parse()` returns `{ ok, value, error }` instead of throwing. Replace `try { parse(s) } catch` with a check on `result.ok`.

### Deprecated
- `parseSync()`: use `parse()`. It will be removed in 5.0.0.

### Fixed
- Error messages no longer report the wrong line number after a byte order mark ([#321]). Thanks @lena-v.

## [3.9.2] - 2026-10-03

### Fixed
- Republished 3.9.1's fixes with a working build.

## [3.9.1] - 2026-10-02 [YANKED]

Published with a broken build. Use 3.9.2.

[Unreleased]: https://github.com/acme/tinyparse/compare/v4.0.0...HEAD
[4.0.0]: https://github.com/acme/tinyparse/compare/v3.9.2...v4.0.0
[3.9.2]: https://github.com/acme/tinyparse/compare/v3.9.1...v3.9.2
[3.9.1]: https://github.com/acme/tinyparse/compare/v3.9.0...v3.9.1
[#318]: https://github.com/acme/tinyparse/pull/318
[#321]: https://github.com/acme/tinyparse/pull/321

Why it works

The summary counts the breaking changes, so upgraders know what they're in for before they read the list.
Each breaking entry carries its one-line upgrade step; the full procedure lives in the migration guide.
The yanked release stays listed and points to the fix, so nobody wonders where 3.9.1 went.
Pair it with GitHub releases: the free GitHub Action copies each version's section into its release when you tag.

Template 5 of 5

Mobile app version history template

Best for: iOS and Android apps: one record of every app version, from which you cut each store's What's new text.

Store notes are short, separate per store and per language, while your team and support need the full story. Keep one version history in the repository: a section per app version and build with the store text you shipped and the details behind it. fastlane, for example, reads App Store notes from fastlane/metadata/<locale>/release_notes.txt and Google Play notes from fastlane/metadata/android/<locale>/changelogs/<versionCode>.txt, so the store text can go straight from this file into those.

CHANGELOG.md · template

## [App version] (build [build number]) - YYYY-MM-DD

Platforms: [iOS / Android] · Rollout: [phased / 100%] · Minimum OS: [iOS version, Android version]

### Store text
[The What's new text exactly as submitted: the main change first, a few short lines, plain text.]

### Details
- Added: [feature, and where to find it]
- Changed: [behavior that works differently]
- Fixed: [the bug people reported]

### Notes for support
- [Known issues, workarounds, server-side flags that must be on]

Filled in: two releases of a task app

CHANGELOG.md · example

## 5.2.0 (build 5200) - 2026-11-03

Platforms: iOS and Android · Rollout: phased · Minimum OS: iOS 17, Android 9

### Store text
New calendar view: see your dated tasks at a glance and drag a task to another day.
• Recurring tasks: daily, weekly or custom.
• Fixed: reminders no longer arrive twice for shared tasks.

### Details
- Added: calendar view under the Today tab; drag a task to reschedule it.
- Added: recurring tasks with daily, weekly and custom schedules.
- Fixed: shared tasks sent one reminder per assignee instead of one in total.

### Notes for support
- The calendar view needs the calendar_v2 server flag, which is on for everyone since 3 November.

## 5.1.1 (build 5110) - 2026-10-18

Platforms: Android · Rollout: 100% · Minimum OS: Android 9

### Store text
Fixes a crash when opening a task from a notification on some Android 14 devices.

Why it works

The store text is kept word for word, so support can see exactly what people read.
Store text stays within the limits: up to 4,000 characters on the App Store, 500 per language on Google Play.
Rollout and minimum OS answer the most common support question: why don't I have it yet?
Write the store text itself with the app store What's new template.

Before you publish

Newest version first, each with its version (or date) and a YYYY-MM-DD release date.
An Unreleased section at the top collects changes as they merge.
Every breaking change carries Breaking: and a one-line upgrade step.
Deprecations name the replacement and the version that removes them.
Security entries lead with the CVE identifier when there is one.
Version headings link to their diff, with the references at the bottom of the file.
No raw git log: only changes people would notice, written for them.
Yanked releases stay listed, marked [YANKED].

Common questions

What is a changelog template?

A ready-made structure for the file or page where you record every notable change, version by version. You don't have to decide headings and order each time, and consistent entries are easier to read for people and for tools, coding agents included.

What should a CHANGELOG.md look like?

Start with a # Changelog heading and a short preamble naming the format and versioning scheme. Then an ## [Unreleased] section, then one section per version such as ## [1.4.0] - 2026-11-03, newest first, with changes under Added, Changed, Deprecated, Removed, Fixed and Security. Reference links at the bottom point each version at its diff. That's the Keep a Changelog 2.0.0 format, shown in template 2.

Is Keep a Changelog the same as a changelog template?

Keep a Changelog is a widely used set of conventions for CHANGELOG.md files; a template is a starting file that follows a set of conventions. Templates 2 and 4 here follow Keep a Changelog 2.0.0, and the others adapt the same idea for customers and app stores.

Should I generate my changelog from commits?

Use commits as raw material, not as the changelog. Keep a Changelog warns against using a list of commits: many commits don't matter to readers, and one change often spans several. A draft from your merged pull requests, like the one the free release notes generator writes, saves typing; then cut and reword it. Generate a changelog from git compares the tools.

Where should a SaaS product keep its changelog?

On a public page with its own address, so people can find and share it, and inside the product, where customers notice what's new. LogPulse publishes the same entries to a hosted changelog, an in-app widget and a JSON feed. The SaaS template works in any tool.

How do I record breaking changes in a changelog?

Mark them **Breaking:** on the entry, under Changed or Removed, rather than in a separate section, and add a one-line upgrade step. If you follow Semantic Versioning, they go in a major version. Announce them in your release notes too. How to document breaking changes covers what to write.

Can coding agents read my changelog?

Yes, when it follows a consistent format. Agents like Claude Code and Cursor can read a CHANGELOG.md to decide what to change when they upgrade a dependency. Paste yours into the free changelog-to-JSON converter to see which versions, breaking changes and deprecations they can pick out.

Do I need a separate changelog for each app store?

No. Keep one version history (template 5) and cut each store's text from it: up to 4,000 characters for the App Store's What's New in This Version and up to 500 Unicode characters per language for Google Play.

Sources

Store limits and format rules last checked against these sources on 13 November 2026. The products, people and links in the examples are made up.

Announcing one release

Release notes templates you can copy today

Copy 5 release notes templates: Markdown, Keep a Changelog, SaaS customer updates, open-source GitHub releases and app store What's new, each filled in.

See the release notes templates

Open-source libraries and packages

All release notes guides

Tools and resources

LogPulse

Changelogs coding agents can upgrade from.

Publish versions, breaking changes, migration steps and deprecations once. People get a widget and hosted changelog; agents get a JSON feed and MCP server. Free for open source.

Create your changelog See an upgrade guide

Changelog templates for every kind of project

Start your changelog from your merged pull requests

The short answer

Which template should you use?

Simple Markdown changelog template

Filled in: an internal reporting tool

Keep a Changelog template (CHANGELOG.md)

Filled in: a small command-line tool, three versions

Turn each version section into a GitHub release

SaaS product changelog template

Filled in: two months of an invoicing app

Open-source library changelog template

Filled in: a JavaScript library's major release

Mobile app version history template

Filled in: two releases of a task app

Before you publish

Common questions

Sources

Release notes templates you can copy today

CHANGELOG.md format, explained line by line

Changelog vs release notes: what's the difference?

Keep a Changelog vs GitHub Releases

How to generate a changelog from git commits

Semantic versioning cheat sheet for changelogs

How to write deprecation notices

Tools and resources

Changelogs coding agents can upgrade from.

Start your changelog from your merged pull requests

The short answer

Which template should you use?

Simple Markdown changelog template

Filled in: an internal reporting tool

Keep a Changelog template (CHANGELOG.md)

Filled in: a small command-line tool, three versions

Turn each version section into a GitHub release

SaaS product changelog template

Filled in: two months of an invoicing app

Open-source library changelog template

Filled in: a JavaScript library's major release

Mobile app version history template

Filled in: two releases of a task app

Before you publish

Common questions

Sources

Release notes templates you can copy today

Related guides

CHANGELOG.md format, explained line by line

Changelog vs release notes: what's the difference?

Keep a Changelog vs GitHub Releases

How to generate a changelog from git commits

Semantic versioning cheat sheet for changelogs

How to write deprecation notices

Tools and resources

Changelogs coding agents can upgrade from.