Release notes template (and a changelog format that works)
Free release notes and changelog templates: customer-facing notes, the Keep a Changelog format with its six change types, and filled-in examples.
A release ships with notes that read "Various bug fixes and performance improvements." Two customers miss that an API field was deprecated, and their integrations break three months later when it's removed. The information existed in a commit message. Nobody wrote it for the people who needed it.
This guide gives templates for both release notes and a changelog, following Keep a Changelog, checked on 16 November 2026.
Release notes vs changelog
| Changelog | Release notes | |
|---|---|---|
| What | Running record of notable changes, per version | Announcement for one release |
| Reader | Developers, integrators, power users | Customers, the whole user base |
| Tone | Factual, grouped by type | Benefit-led |
| Where | CHANGELOG.md, docs site | Email, in-app, blog, status page |
The changelog format
Keep a Changelog's guiding principles:
- Changelogs are for humans, not machines.
- An entry for every version.
- Group the same types of changes.
- Versions and sections are linkable.
- Latest version first.
- Show each version's release date.
- Say whether you follow Semantic Versioning.
Change types:
| Type | For |
|---|---|
| Added | New features |
| Changed | Changes to existing functionality |
| Deprecated | Features to be removed soon |
| Removed | Features removed now |
| Fixed | Bug fixes |
| Security | Vulnerabilities |
Changelog template
# Changelog
All notable changes to this project are documented here.
This project follows Semantic Versioning.
## [Unreleased]
### Added
-
## [2.4.0] - 2026-11-16
### Added
- CSV export of the member list, filtered by role.
### Changed
- Members list now sorts by last active date by default.
### Deprecated
- `GET /v1/members?page=` offset pagination. Use cursors; removal in 3.0.
### Fixed
- Invite emails no longer expire early for users in UTC+ time zones.
### Security
- Session tokens now rotate on password change.
The Unreleased section at the top collects changes as they merge; at release time, move them under the new version.
Release notes template
# [Product] [version or date]: [one-line headline]
## What's new
**[Feature name].** [What it does and why it helps, in 1 to 2 sentences.]
[Link to docs or a short demo]
## Improvements
- [Visible improvement, in user terms]
## Fixes
- [Bug users would have noticed]
## Changes you should know about
- [Anything that changes existing behavior, deprecations, and what to do]
Example
# Workspace 2.4: export your member list
## What's new
**Member export.** Download your member list as a CSV, filtered to
match what's on screen, for access reviews and audits. [How to export]
## Improvements
- The members list now opens sorted by last active date.
## Fixes
- Invite emails no longer expire early in some time zones.
## Changes you should know about
- Offset pagination on the members API is deprecated and will be
removed in version 3.0. Switch to cursors before then. [Migration guide]
Rules that prevent bad release notes
- Don't paste the commit log. Keep a Changelog calls it noise: merge commits, obscure titles, internal changes.
- Always list deprecations and breaking changes. Its advice: if you do nothing else, list deprecations, removals, and breaking changes.
- Use ISO dates, like 2026-11-16.
- Write for the reader. "Faster search" beats "Optimized query planner."
- Link to details instead of explaining everything.
Release notes record decisions
"Offset pagination is deprecated, removal in 3.0" is a decision with a date. It needs to reach customers, and also every engineer and AI coding agent still writing new code against offset pagination.
Where Lockstep fits
Lockstep captures decisions like deprecations from PRDs, Slack, and pull requests, routes each to its owner for approval, and briefs Claude Code sessions on the ones that apply, so new code follows the deprecation as soon as it's decided.
See Lockstep for product teams.
Sources checked 16 November 2026
Related reading
For keeping APIs compatible, see API design best practices. For shipping safely, see feature flag best practices. For everything else before shipping, see the launch checklist.
Frequently asked questions
- What is the difference between release notes and a changelog?
- A changelog is a curated, chronological list of notable changes for each version, often a CHANGELOG file in the repository. Release notes are the announcement for one release, written for customers, focused on what's new and why it matters. Many teams keep both, with release notes drawn from the changelog.
- What should release notes include?
- A short headline, what's new and the benefit to the user, improvements, fixes users would notice, anything that changes or breaks existing behavior with what to do about it, and a link to docs. Keep internal details out.
- What sections should a changelog have?
- Keep a Changelog groups changes as Added, Changed, Deprecated, Removed, Fixed, and Security, with an Unreleased section at the top for upcoming changes, the latest version first, and a release date for each version.
- Can I generate release notes from commit messages?
- Keep a Changelog advises against using commit log diffs as changelogs: they're full of noise like merge commits and obscure titles. A changelog entry documents the noteworthy difference, often across many commits, for users.
- What date format should a changelog use?
- YYYY-MM-DD, such as 2026-11-16. Keep a Changelog recommends it because it orders from largest to smallest unit, avoids regional ambiguity, and is an ISO standard.
Keep reading