What is Changelog vs Release Notes?
Last reviewed May 28, 2026
A changelog is the running log of all changes a product or codebase ships over time, kept as one continuous chronological record. Release notes are the per-release subset of that log written for the audience that consumes a specific version — usually customers or downstream developers. In practice the terms overlap and many teams use them interchangeably; the substantive difference is scope (all changes vs one release) and often audience (engineering reference vs user communication).
Example
An open-source library's CHANGELOG.md file (one document covering every version since v1.0) is the changelog. The notes attached to the v2.3.0 GitHub Release (just covering what changed in 2.3.0) are the release notes for that release. Both can exist for the same product — the GitHub Releases page is essentially a changelog rendered as a series of release notes entries.
Why it matters
The distinction matters for two practical reasons. First, when shopping for tools, "changelog tool" and "release notes tool" surface different products in different categories — knowing which word a vendor uses tells you whether they think of themselves as a running-log product (Herald, Headway) or a per-release-author product (some PRD tools). Second, when writing, scope shifts copy: changelog entries are written in past tense for the historical record; release notes are written for a specific moment of "this is what we just shipped."
More context
The two terms are close enough that 90% of the time it doesn't matter which you use — and most teams treat them as synonyms. But if you're writing about the topic, or you're shopping for tools, or you're explaining the workflow to a new teammate, the distinction is worth a few sentences.
The scope difference
A changelog is one document, growing over time. Versions or releases are sections within it. The current state of CHANGELOG.md in a long-lived open-source project contains every release since the project started.
Release notes are usually one document per release, written at the time of that release. The Stripe API team publishes a notes entry every time they ship; together those entries form Stripe's API changelog.
In a hosted-tool context (Herald, Headway, AnnounceKit, etc.), each "release" you publish through the tool is a release notes entry, and the hosted page that lists all of them in chronological order is the changelog. Same words, two layers.
The audience difference
This is where the terms diverge in practice:
- Engineering-flavored "changelog" lives at
CHANGELOG.mdin the repo, on GitHub Releases, in package-manager metadata. The audience is other engineers — contributors, downstream library consumers, integrators. - Customer-flavored "release notes" lives on your hosted product page, in your in-app widget, in subscriber email. The audience is the people who use the product — typically not engineers.
This distinction is the gap between CHANGELOG.md content (terse, version-keyed, "Fix: race condition in token refresh handler") and customer release notes content (richer, user-focused, "Fixed a sign-in issue some users hit after their session expired"). Same release, different audiences, two pieces of writing.
For teams that ship on GitHub, this used to mean maintaining both by hand. Herald closes that gap by reading your PRs to draft the customer-facing version AND publishing back to GitHub Releases — see the Herald and GitHub Releases guide for the bidirectional flow.
Which word should you use?
- In your own product UI: pick one and stay consistent. Most SaaS teams use "What's new" or "Updates" for the user-facing surface, "Changelog" or "Release notes" for the dedicated page.
- In your engineering process:
CHANGELOG.mdis the universal filename; nobody calls itRELEASE_NOTES.md. - When searching for tools: search both. The category is small enough that the same vendors show up under both queries — but the framing in their copy will tell you which audience they're built for.
Related terms
Want to go deeper? Read How to write release notes users actually read.