Changelog vs release notes: what's the difference?
Both describe what changed, so people use the words interchangeably. In practice they answer different questions: a changelog answers “what changed in each version?”, release notes answer “what does this release mean for me, and what do I need to do?”. Most libraries people depend on keep both.
Updated Last checked 6 min readOpen-source libraries and packages
The short answer
- A changelog is one file, usually
CHANGELOG.md, with the notable changes of every version, newest first. Keep a Changelog calls it “the complete, ongoing record”. - Release notes are “an announcement for a single release”: its headline changes, often with upgrade steps. They live on a GitHub release, a blog post or a docs page.
- Keep the changelog as the source and draw the release notes from it, rather than maintaining two separate lists.
- Python's packaging metadata names both: a Changelog link is “the project's comprehensive changelog”, a Release Notes link is “the project's curated release notes”.
- Neither is a git log. Both are written for the people upgrading, not for the people who reviewed the code.
One release, written both ways
The same 2.0.0 release as a changelog entry (complete and terse) and as release notes (the story, the highlights and what to do before upgrading). Delete the half you don't need.
<!-- In CHANGELOG.md: the complete record -->
## [2.0.0] - YYYY-MM-DD
### Changed
- **Breaking:** `parse()` throws `ParseError` on invalid input instead of returning `null`.
### Added
- `parseStream()` for large inputs (#412).
### Removed
- **Breaking:** Node.js 18 support. Node.js 20 or later is required.
<!-- In the GitHub release for v2.0.0: the story of this release -->
# my-lib 2.0.0
A streaming parser, clearer errors and a modern Node.js baseline.
## Highlights
- Parse multi-gigabyte files with `parseStream()` without loading them into memory.
## Before you upgrade
1. Run Node.js 20 or later.
2. Wrap `parse()` calls that accept user input in try/catch and handle `ParseError`.
Every change: CHANGELOG.md · Compare: v1.9.0...v2.0.0The package name, functions and pull request number are placeholders. Replace them with what you actually shipped.
Free tool · no sign-up
Can a coding agent read your changelog?
Paste your repository, a GitHub release or a CHANGELOG.md link. The free converter shows every version, breaking change, migration step and deprecation it can extract, as JSON plus an llms.txt summary.
No AI and nothing stored. Or paste a CHANGELOG.md instead
01What a changelog is
A changelog is a single file in the repository, conventionally named CHANGELOG.md, with one entry per released version. Keep a Changelog 2.0.0 defines it as “a curated, chronologically ordered list of the notable changes for each version of a project”, kept “to make it easy for users and contributors to see the notable changes between each version.” It's cumulative: every release adds an entry at the top and old entries stay, so anyone can answer “when did this change?” years later.
Because it's one predictable file with one heading per version, a changelog is also what tools read: package registries link to it, dependency bots quote it, and coding agents parse it when they upgrade your library. See the CHANGELOG.md format for the exact conventions.
02What release notes are
Keep a Changelog describes release notes as “an announcement for a single release: a curated selection of its headline changes, often with upgrade steps and a marketing voice, published when that version ships.” On GitHub they're attached to a release: GitHub's docs say “Releases are based on Git tags”, and you can create one “to package software, along with release notes and links to binary files”.
Release notes reach people a changelog file doesn't: GitHub lets users get notified “when new releases are published in a repository without receiving notifications about other updates”. Bigger projects also publish them as a blog post or a docs page, often with a separate migration guide.
03Side by side
| Changelog | Release notes | |
|---|---|---|
| Scope | Every version, newest first | One release |
| Where it lives | CHANGELOG.md in the repository | A GitHub release, blog post, docs page or in-app announcement |
| Written for | Anyone checking what changed and when, including tools | The people affected by this release |
| Style | Terse lines grouped as Added, Changed, Deprecated, Removed, Fixed, Security | Highlights first, then breaking changes with upgrade steps |
| Breaking changes | Listed, ideally at the top of the entry | Explained, with before/after code or a link to a migration guide |
| Reaches people | When they go looking | Through release notifications, feeds and announcements |
Neither term has a formal standard. This is the distinction Keep a Changelog 2.0.0 draws, that the projects below follow, and that Python packaging metadata uses for its “comprehensive changelog” and “curated release notes” links.
04Do you need both?
- A small library: keep
CHANGELOG.mdand paste each entry into the GitHub release for the tag. Keep a Changelog vs GitHub Releases shows how to keep them in sync. - A major version of anything: add real release notes with upgrade steps, and warn people before release day. See how to announce breaking changes and how to document breaking changes.
- A SaaS product: customers read release notes (a hosted changelog page, an in-app widget, email); the engineering changelog can stay internal. See release notes for SaaS.
- A public API: client developers need both, plus dates. See release notes for APIs.
05Keep them consistent
Write the changelog entry first, as pull requests merge, and derive the release notes from it on release day. Keep a Changelog's advice: “Keep the changelog as the record, and write the release notes from it rather than maintaining two.” At release time, the version's section “is already the draft: copy it into the release, and expand it only if the announcement wants more.” Use the same version numbers and dates in both, and link each to the other.
Don't rely on your code host alone. Release pages, including notes GitHub generates from pull requests, are stored by the host rather than in your repository, which Keep a Changelog calls out: “your changelog goes where your code goes; what a host generates and keeps for you does not.” And don't let one swallow the other: Common Changelog says “a changelog is not a blog or detailed upgrade guide” and that those “must be kept separate from the changelog”.
Coding agents increasingly do the upgrading. They read the changelog, so make sure breaking changes and deprecations are explicit there too, not only in a blog post. The open-source release notes guide has a template that works for both readers.
Real projects that do this well
Public release notes worth copying from. Each link opens the project's own page.
- React: CHANGELOG.md The repository's changelog lists new features, APIs, deprecations and breaking changes for every version.
- React: the React 19 release post Release notes as a blog post: an overview of what's new in React 19 and how to adopt it, with examples.
- Rust: RELEASES.md Every version with its date and categorized changes, each linked to the pull request that made it.
- Rust: the 1.85.0 announcement The story of the release: what's new, how to update and a link to the detailed notes.
- Kubernetes: CHANGELOG-1.32.md One changelog file per minor series, with downloads, checksums and every change in each patch release.
- Kubernetes: the v1.32 release blog The release theme, the highlights and which enhancements graduated to stable, beta or alpha.
Before and after
Too vague
Release notes for 2.0.0: see the commit history.
Specific and actionable
2.0.0 adds parseStream() for large files. Before upgrading: run Node.js 20+, and catch ParseError where parse() handles user input. Every change is in CHANGELOG.md.
Fictional example: use your own verified names, versions and behavior.
LogPulse
Generate release notes with LogPulse
LogPulse is a hosted changelog that people and coding agents can both read. Here's exactly what it can do for the steps above, and what it can't.
Check your changelog, free
Paste a CHANGELOG.md or a GitHub releases link. A deterministic parser (no AI, nothing stored) shows the versions, breaking changes, migration steps and deprecations an agent can extract.
Draft notes from GitHub
Connect a repository: merged pull requests, commits to your default branch and published GitHub releases collect in an inbox. AI drafts a note in the tone you pick, listing breaking changes and deprecations only when the changes clearly show them. Nothing is published until you approve it. 3 AI drafts on Free; unlimited on Open source and Pro. Pro opens soon: .
Publish once, read everywhere
Approved notes go to a hosted changelog and an in-app widget, to email subscribers on Open source and Pro (Pro opens soon), and to a JSON feed and MCP server coding agents can query. CI and agents can publish with an API key.
What it doesn't do: LogPulse doesn't tag releases, bump versions, publish to npm or PyPI, or write CHANGELOG.md back to your repository; keep your release tooling for those. AI drafts can miss context, so review them like a pull request.
Before you publish
- CHANGELOG.md has an entry for this version with today's date
- The release notes lead with highlights and breaking changes, not a commit list
- Every breaking change has an upgrade step in the release notes
- Both use the same version number, and link to each other
- Breaking changes and deprecations are explicit in the changelog too, for tools and agents
Common questions
Is a changelog the same as release notes?
No, although they draw from the same material. A changelog is the complete record of every version in one file; release notes announce a single release for the people it affects. Many small projects copy the changelog entry into the release, which Keep a Changelog recommends as the starting point.
Should release notes list every change?
No. Lead with what matters to the reader: highlights, breaking changes and anything they must do. Link to the changelog or a compare view for the full list.
What's the difference between a changelog and a git log?
A git log is every commit, written for reviewers. A changelog is curated for users: Keep a Changelog says “Do not use a list of commits as a changelog. It is full of noise.” You can still draft a changelog from git commits and then edit it.
Where should I publish release notes?
Where your users already look: a GitHub release for libraries (people can subscribe to releases only), a blog or docs page for major versions, and a hosted changelog page, in-app widget or email for products.
Sources
Facts last checked against these sources on .
Read next
Keep a Changelog vs GitHub Releases
CHANGELOG.md or GitHub Releases? See them side by side, when to use each, and how to keep both in sync with release.yml. Includes a CHANGELOG.md skeleton.
Read the guide Open-source libraries and packagesCHANGELOG.md format, explained line by line
The CHANGELOG.md format most projects follow: version headings, YYYY-MM-DD dates, the six change types, Breaking markers, Unreleased, yanked versions and links.
Read the guide Open-source libraries and packagesHow to write release notes for open-source libraries
How to write release notes: a copy-paste template, 3 examples (library, CLI, breaking change), a 7-point checklist and how Django and Node.js do it.
Read the guide Breaking changes, deprecations and versioningHow to announce breaking changes
When and where to warn users about a breaking change: deprecate in a minor first, ship the major with migration steps, reach every channel. Template included.
Read the guideMore guides: open-source libraries and packages
- Release notes templates in Markdown
- How to generate a changelog from git commits
- How to write release notes from commits (Conventional Commits)
- semantic-release vs release-please vs Changesets (and git-cliff)
- How to keep a changelog for an npm package
- How to keep a changelog for a Python package on PyPI
Tools and resources
LogPulse
Changelogs coding agents can upgrade from.
Publish versions, breaking changes, migration steps and deprecations once. People get a widget and hosted changelog; agents get a JSON feed and MCP server. Free for open source.