Changelog Template — CHANGELOG.md Format with Examples

The standard CHANGELOG.md template

The Keep a Changelog format is the most widely adopted convention. It uses six fixed section types and reverse-chronological versioning.

CHANGELOG.md — full 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/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] ### Added - Placeholder for upcoming features ## [1.2.0] - 2026-06-01 ### Added - New feature description in plain language (#142) - Another feature users asked for (#138) ### Changed - Existing behaviour that was updated, and what it does now ### Deprecated - Feature that will be removed in a future version ### Removed - Feature that has been removed and the alternative ### Fixed - Bug that was affecting users and the symptom it caused (#155) - Another fix, described from the user's perspective (#149) ### Security - Dependency updated to address CVE-2026-1234 ## [1.1.0] - 2026-04-15 ### Added - Previous feature ### Fixed - Previous fix ## [1.0.0] - 2026-01-20 ### Added - Initial release [Unreleased]: https://github.com/org/repo/compare/v1.2.0...HEAD [1.2.0]: https://github.com/org/repo/compare/v1.1.0...v1.2.0 [1.1.0]: https://github.com/org/repo/compare/v1.0.0...v1.1.0 [1.0.0]: https://github.com/org/repo/releases/tag/v1.0.0

Minimal template (just the sections you need)

Most releases only use two or three sections. You don't have to include empty sections — only add the ones with content.

CHANGELOG.md — minimal

# Changelog ## [Unreleased] ## [1.0.1] - 2026-06-03 ### Fixed - Crash on startup for users with special characters in username

The six section types explained

Added — New features. Anything a user can do now that they couldn't before.
Changed — Existing features that work differently. Includes UI changes.
Deprecated — Features that still work but will be removed. Give users time to migrate.
Removed — Features that no longer exist. Say what to use instead.
Fixed — Bug fixes. Describe the symptom, not the implementation.
Security — Vulnerability fixes. Link to the CVE where applicable.

Rules for good changelog entries

Write for users, not developers. "Fix NPE in AuthController" is a commit message. "Fix crash when logging in with a Google account" is a changelog entry.
One line per change. If an entry needs more than one sentence, it's probably two changes.
Most recent version at the top. Readers want to know what changed now, not in 2023.
Keep [Unreleased] at the top. It collects changes for the next release as you go.
Date every version. [1.2.0] - 2026-06-01 gives context about the pace of development.

FAQ

Where should CHANGELOG.md live?

In the root of your repository, alongside README.md. GitHub renders it automatically.

Should I maintain a changelog for every project?

For anything with external users or dependents, yes. For internal tools or personal projects, it's optional but worth it — changelogs are as useful to your future self as they are to others.

What's the difference between a changelog and release notes?

A changelog is the cumulative record in CHANGELOG.md. Release notes are platform-specific communications for each release. They often cover the same content but in different formats. See the full comparison.

Is ChangelogAI free?

Yes — completely free. Unlimited generations, no account required.

Generate from your commits automatically

Paste your git log and get a formatted CHANGELOG.md entry in seconds. Completely free, no account needed.

generate free →

No account · No limits · Works with any git workflow