What is the Keep a Changelog format?

Keep a Changelog is a widely adopted convention for structuring changelogs with versioned headings, ISO date stamps, and categorized entries under Added, Changed, Fixed, Removed, and Security.

Should I write a changelog or use git log?

Write a curated changelog. Raw git logs include merge commits and minor fixes that mean nothing to users. A changelog communicates user-visible changes in clear language.

Where should I put the Unreleased section?

At the top of the file, above all version headings. Accumulate changes there during development and rename the section to the new version number when you release.

Write a CHANGELOG in Markdown

A structured changelog tells users what changed between versions and why, building trust that maintainers communicate clearly. The Keep a Changelog format organizes entries into Added, Changed, Deprecated, Removed, Fixed, and Security sections under semantic version headings. This template follows that convention and includes an Unreleased section for changes not yet released. The Markdown formatter ensures consistent heading levels and list indentation before you commit.

Example

# Changelog

All notable changes to this project will be documented in this file.
Format based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).

## [Unreleased]

### Added
- Dark mode support for all UI components

## [2.1.0] - 2026-03-15

### Added
- Export to PDF feature
- Keyboard shortcut reference panel

### Changed
- Improved error messages for API failures

### Fixed
- Resolved race condition in async data loader

## [2.0.0] - 2026-01-10

### Changed
- Migrated from REST to GraphQL API (breaking change)

### Removed
- Deprecated v1 endpoints

[ open in Markdown Formatter → ]

FAQ

What is the Keep a Changelog format?: Keep a Changelog is a widely adopted convention for structuring changelogs with versioned headings, ISO date stamps, and categorized entries under Added, Changed, Fixed, Removed, and Security.
Should I write a changelog or use git log?: Write a curated changelog. Raw git logs include merge commits and minor fixes that mean nothing to users. A changelog communicates user-visible changes in clear language.
Where should I put the Unreleased section?: At the top of the file, above all version headings. Accumulate changes there during development and rename the section to the new version number when you release.

Related Examples

Write a Project README in Markdown

A good README is the front door of every open-source project and sets the tone f...

Write a CONTRIBUTING Guide

A contributing guide reduces friction for new contributors by explaining how to ...

Pull Request Description Template

A consistent pull request template speeds up code review by ensuring authors inc...