Understanding changelogs
What changed, for the human who'll upgrade.
The "Keep a Changelog" structure, the six section names, and the difference between a release log and a commit log.
A changelog is not a commit log.
The commit history is the raw record of every change. The changelog is a curated summary aimed at the user upgrading from version X to X+1. Auto-generated "list every commit" changelogs read like a git log dump — fine for internal CI, terrible for end users. The discipline is selection: which changes actually matter to someone upgrading? That's the changelog.
The Keep a Changelog format.
Olivier Lacan's 2014 spec is the de facto standard. Six section names: Added, Changed, Deprecated, Removed, Fixed, Security. One section per release, with the version number and date as the header. Latest release at the top. An [Unreleased]section accumulates changes for the next version. The format is plain Markdown — no tools required to write or read it.
Semantic versioning is the partner.
MAJOR.MINOR.PATCH. Breaking changes bump MAJOR, new features bump MINOR, bug fixes bump PATCH. The changelog and the version number tell the same story from different angles: the number tells you how risky the upgrade is, the changelog tells you what to look at. Tools like semantic-release link them — Conventional Commit prefixes decide the bump and populate the changelog automatically.
A worked entry.
A real changelog block: "## [2.4.0] - 2026-05-14 ### Added — Support for OAuth 2.1 PKCE flow (#1234). New `--quiet` CLI flag suppresses non-error output. ### Changed — Default timeout raised from 5s to 10s (closes #1199). ### Deprecated — The `legacy()` helper, removed in 3.0. ### Fixed — Race condition when calling `flush()` during shutdown (#1241)." Each line is a short, present-tense sentence that names what changed and references the issue or PR. No commit hashes, no internal refactors, no dependency bumps that don't affect users.
[2.4.0] release
6 sections, present tense
One line per user-visible change, link the issue.
Added 2 ; Changed 1 ; Deprecated 1 ; Fixed 1
= The upgrade brief
What to leave out.
Skip refactors that don't change behaviour, dependency bumps that aren't user-visible, documentation updates, internal test changes, and CI config. They belong in the commit log but they make the changelog noisy. The user upgrading doesn't care that you switched from Jest to Vitest internally — only that the public API still behaves. If in doubt, ask "would this make a user re-read their integration code?" — if no, leave it out.
Automation has limits.
Tools that scrape Conventional Commits into a changelog (release-please, semantic-release, Changesets) save real work, but they produce mechanical text. The best changelogs are auto-generated then hand-edited: the tool grabs the commits, a human rewrites the user-facing summary and decides what to drop. The result reads like documentation, not like a CI artifact. That last pass is the difference between a changelog people read and one they ignore.