Blog

Keep a Changelog template (copy and paste)

· 7 min read

Keep a Changelog is a convention for writing a CHANGELOG.md file: one entry per version, newest first, with changes grouped under six standard headings. The template below follows version 1.1.0 of the format. Copy it into your repository, replace the placeholder lines, and you have a changelog in a format readers already know where to look in.

The template

Save this as CHANGELOG.md in the root of your project:

# 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/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [1.1.0] - 2026-11-07

### Added
- New feature, described from the reader's point of view.

### Changed
- Behaviour that works differently now.

### Deprecated
- Feature that will be removed in a future version.

### Removed
- Feature that is gone in this version.

### Fixed
- Bug that no longer happens.

### Security
- Vulnerability that was fixed, and who was affected.

## [1.0.0] - 2026-10-01

### Added
- Initial release.

[Unreleased]: https://github.com/your-name/your-project/compare/v1.1.0...HEAD
[1.1.0]: https://github.com/your-name/your-project/compare/v1.0.0...v1.1.0
[1.0.0]: https://github.com/your-name/your-project/releases/tag/v1.0.0

Delete the headings you do not use in a given release. An entry with only Fixed is perfectly fine. The comparison links at the bottom let readers jump from a version heading to the exact code that changed between releases.

# Changelog## [Unreleased]## [1.1.0] - 2026-11-07### Added- Export reports to PDF### Fixed- Login redirect loop[1.1.0]: …/compare/v1.0.0...v1.1.01Upcoming changes2Version and ISO date3One of six types4Link to the exact diff
The parts of a Keep a Changelog file.

The guiding principles

The format comes from a short list of principles published at keepachangelog.com. In practice they mean:

  • A changelog is for humans, not machines. Write for the person who has to decide whether to upgrade.
  • There is an entry for every version.
  • Changes of the same type are grouped together.
  • Versions and sections can be linked to.
  • The latest version comes first.
  • The release date of each version is shown.
  • You say whether you follow Semantic Versioning.

The six types of change

Every entry goes under one of six headings:

  • Added for new features.
  • Changed for changes in existing functionality.
  • Deprecated for features that will be removed soon.
  • Removed for features that are now gone.
  • Fixed for bug fixes.
  • Security in case of vulnerabilities.

Keeping to these six makes your changelog predictable. A reader scanning for breaking changes knows to look under Changed and Removed, and a reader checking whether their bug is fixed knows to look under Fixed.

Using the Unreleased section

Keep an [Unreleased] heading at the top. As pull requests merge, add a line under it. This has two benefits: readers can see what is coming, and you no longer have to reconstruct the release from memory.

When you cut a release, move the entries from Unreleased into a new version section with its date, and leave Unreleased empty at the top. Update the comparison links at the bottom at the same time.

How it works with Semantic Versioning

Keep a Changelog does not prescribe a numbering scheme, but it asks you to mention whether you follow Semantic Versioning, and it pairs naturally with Semantic Versioning 2.0.0, which numbers releases as MAJOR.MINOR.PATCH:

  • Increase the major version when you make incompatible changes, such as a removed feature.
  • Increase the minor version when you add functionality in a backward compatible way.
  • Increase the patch version when you make backward compatible bug fixes.

The headings give you a quick check. An entry with Removed, or a Changed line that breaks existing behaviour, points to a major release. An entry with only Fixed is usually a patch.

MAJOR2.0.0IncompatibleAPI changeRemoved, or a breaking ChangedMINOR1.3.0New feature,backward compatibleAddedPATCH1.2.1Bug fix,backward compatibleFixed
How the kind of change maps to the version number (Semantic Versioning 2.0.0).

Yanked releases

Sometimes you have to pull a release because of a serious bug or a security problem. Keep it in the file so the history stays honest, and mark the heading:

## [1.0.1] - 2026-10-15 [YANKED]

Common mistakes

  • Pasting the commit log. Commit messages describe the code. Entries should describe the effect on the reader.
  • Mixing types. A fix hidden under Added is easy to miss.
  • Skipping dates. Use the ISO format YYYY-MM-DD, so the date means the same thing everywhere.
  • Rewriting history. Correct mistakes, but do not quietly delete old entries.
  • Forgetting the links. Comparison links turn each heading into a way to see the actual diff.

For advice on wording the entries themselves, read how to write a changelog. If the file is for developers and a separate version is for customers, see changelog vs release notes.

Generating entries in this format

If writing the entries is the slow part, ReleaseTale drafts the developer version in this style: grouped headings, pull request links and breaking changes called out. It works from commit messages, pull request titles and descriptions, and file names, and you review the result before saving. You can see what that output looks like on the examples page.