Write a CHANGELOG in Markdown

A CHANGELOG is the communication channel between library maintainers and the developers who depend on their code. When an npm update breaks something or introduces a new feature, users turn to the CHANGELOG to understand what changed, whether the change affects them, and what action they need to take. A well-maintained CHANGELOG is one of the clearest signals that a project is professionally maintained and safe to depend on. The Keep a Changelog format (keepachangelog.com) has become the de facto standard for open-source projects. It specifies a predictable structure: each version has a heading with the version number and release date in ISO 8601 format, and entries are organized under specific categories — Added (new features), Changed (behavior changes to existing features), Deprecated (features that will be removed), Removed (features removed in this version), Fixed (bug fixes), and Security (vulnerability fixes). This categorization makes it instantly clear whether an update brings new features, breaking changes, or security fixes. The Unreleased section at the top is the key workflow feature: as you develop the next version, you accumulate changes under [Unreleased] rather than under a specific version number. When you're ready to release, you rename [Unreleased] to the new version number, add the release date, and create a fresh empty [Unreleased] section for future changes. This keeps the CHANGELOG always current without requiring a separate release step. Breaking changes deservedspecial treatment: a line in the Changed section that notes "(breaking change)" is often insufficient for a major API change. Consider adding a migration guide section within the version heading that gives users the exact old and new code to update. Developers building on your library need to know not just what changed but exactly how to update their code. Semantic versioning alignment: MAJOR.MINOR.PATCH version numbers communicate the scope of changes at a glance. A MAJOR bump (2.0.0 → 3.0.0) signals breaking changes. A MINOR bump (2.0.0 → 2.1.0) signals new backward-compatible features. A PATCH bump (2.0.0 → 2.0.1) signals backward-compatible bug fixes. Your CHANGELOG categories align with this: Removed and Changed (breaking) belong in major versions; Added belongs in minor versions; Fixed belongs in patch versions. The dates in this template use ISO 8601 format (2026-03-15) which is unambiguous regardless of locale, sorts correctly in version history, and is the format specified by the Keep a Changelog standard. Tips: generate a draft CHANGELOG entry as part of your release process using your git commit history as input. Tools like conventional-changelog and semantic-release can automate this if you follow Conventional Commits message format.

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