CHANGELOG.md

CHANGELOG.md is the convention of keeping a human-readable, chronologically ordered record of the notable changes to a project in a Markdown file at the repository root. The most widely followed shape is Keep a Changelog, which groups entries under version headings using categories like Added, Changed, Deprecated, Removed, Fixed, and Security. It is deliberately written for people, as a complement to machine-readable version tags and diffs.

• Reverse-chronological order - Newest release at the top, with an “Unreleased” section collecting pending changes.
• Standard categories - Added, Changed, Deprecated, Removed, Fixed, and Security keep entries scannable and comparable.
• Semantic versioning ties-in - Version headings usually pair with SemVer so readers can gauge the size of a change at a glance.
• Repo-root discoverability - Living alongside README and LICENSE means humans and tooling both know where to look.

For APIs the changelog is where the human story of change lives — the narrative that a raw OpenAPI diff can’t tell on its own. A well-kept CHANGELOG.md warns integrators about deprecations and breaking changes before they bite, and it feeds the release notes, roadmaps, and developer communications that keep consumers in the loop. As agents and pipelines increasingly consume APIs directly, a consistent, parseable changelog becomes a reliable signal of how disciplined a provider is about versioning and backward compatibility.