Changelog

A changelog is a running record of notable changes to a project, organized by version and written for the people who consume the project rather than the people who build it. Its job is to let anyone — a user upgrading, a developer debugging a regression, a maintainer reconstructing history — answer "what changed, and when" without digging through commit history or diffing releases by hand.

Key components

• Grouped by version and date — each version gets its own dated section, in reverse-chronological order, so the most recent changes are always at the top.
• Categorized changes — entries grouped under clear categories such as Added, Changed, Fixed, Deprecated, Removed, and Security, so a reader can scan for the kind of change they care about rather than reading a flat list.
• Written for the consumer, not the codebase — each entry describes the change in terms of what a user or integrator observes ("the export endpoint now returns paginated results"), not the internal mechanism that produced it.
• Unreleased section — a running "Unreleased" or "Upcoming" section at the top where entries land as changes merge, so the record exists before a release ships rather than being reconstructed at release time.
• Links to relevant detail — a reference to the issue, PR, or Release Notes entry for a change, for a reader who wants the full story behind one line.

How it differs from release notes

A changelog and release notes are often confused because they cover the same underlying changes, but they serve different readers and different moments:

• Changelog — the complete, cumulative history across every version the project has ever shipped. A reference document a reader consults to look something up.
• Release Notes — the announcement for one specific release, aimed at someone deciding whether and how that release affects them. Narrower in scope, often more promotional or explanatory in tone, and not expected to be a complete historical record on its own.

Release notes for a given version are often drawn from that version's changelog section, trimmed and reframed for an announcement — the changelog stays the durable record either way.

Common pitfalls

• Entries copied straight from commit messages — a commit message written for another developer mid-implementation ("fix null check in parseHeaders") doesn't tell a consumer what actually changed for them; it needs rewriting into consumer-facing language.
• Internal or private changes included as if they matter externally — refactors, internal test changes, or dependency bumps with no observable effect clutter the record and bury the changes a consumer actually needs to see.
• Not updated until release time — when entries are only written at release time, the record of what changed and when gets reconstructed from memory or a commit log after the fact, and details get lost or misattributed to the wrong version.
• No categorization — a flat list of unsorted entries forces every reader to read the whole section just to find, say, the breaking changes.
• Vague entries — "various bug fixes" or "improvements" tells a reader nothing they can act on; a good entry names the specific behavior that changed.
• Missing dates or version numbers — without them, a reader can't tell whether a fix they need already shipped or is still pending.

Learn more

• Release Notes for the per-release announcement drawn from a changelog's entries but aimed at a different moment and reader.
• README Writing for the project overview that typically links out to the changelog rather than restating its history.
• API Documentation for the reference material a changelog entry often needs to update alongside the change itself.
• Architecture Decision Record for recording the reasoning behind a significant change, as distinct from the changelog's brief record that it happened.