CHANGELOG.md explained

What is CHANGELOG.md?

CHANGELOG.md is a Markdown file that records what changed in each version of a project, so people and tools can see its history at a glance.

Jun 13, 2026 · 6 min read

CHANGELOG.md meaning

`CHANGELOG.md` is a curated, chronological list of notable changes for each version of a project. It is written for humans, kept at the repository root, and usually ordered with the newest version first. A good changelog answers one question quickly: what changed between this release and the last one?

The Keep a Changelog format

The widely used Keep a Changelog convention groups entries under headings like Added, Changed, Deprecated, Removed, Fixed, and Security, under each version number and date. Versions typically follow semantic versioning (major.minor.patch).

# Changelog

## [1.2.0] - 2026-06-13
### Added
- Live preview split view

### Fixed
- Autosave on rename

## [1.1.0] - 2026-05-01
### Changed
- Faster file open

Why keep a changelog

Users can see what is new without reading commit logs
Contributors understand recent direction
Support and QA can map bugs to releases
It builds trust by making progress visible

A changelog is a summary for people. Raw Git history is not a substitute, because it is noisy and not written for readers.

How AI tools use CHANGELOG.md

AI coding agents read CHANGELOG.md to understand a project's recent history and current version. That context helps an assistant write accurate release notes, answer "what changed" questions, and avoid suggesting features that were already removed. Paired with a clear README.md, it gives models a fuller picture of the project.

Best practices

Write for humans, not machines
Keep an Unreleased section at the top for upcoming changes
One entry per notable change, grouped by type
Link versions to release tags or diffs where possible
Update it as part of each release, not months later

Edit CHANGELOG.md with a preview

Changelogs use headings, lists, and links, so a preview helps. Draft yours in the Markdown Docs online editor, or download Markdown Docs to edit it on Windows. See more common .md files for AI projects.

Related references

Keep a Changelog the changelog format standard.
Semantic Versioning for version numbering.

FAQ

Where does CHANGELOG.md go?

Place it at the repository root so users, contributors, and tools can find it next to the README.

What is the Keep a Changelog format?

It groups changes under Added, Changed, Deprecated, Removed, Fixed, and Security headings, listed under each version and date, newest first.

Is a changelog the same as Git history?

No. Git history is a complete, noisy log. A changelog is a curated summary of notable changes written for human readers.

Should I use semantic versioning?

It is recommended. Semantic versioning (major.minor.patch) makes the size and risk of each release clear in the changelog.