People use "changelog" and "release notes" interchangeably, and in many teams the same page does both jobs. But they grew out of different needs, and knowing the difference helps you write better versions of each.
Short answer
- A changelog is a running, chronological log of notable changes to a product or project, usually all in one place and kept forever.
- Release notes are a write-up of one specific release: what's in it, why it matters and what users need to do.
A changelog is the history; release notes are the announcement.
The changelog
The term comes from software development, where projects kept a CHANGELOG file in the repository. The widely adopted Keep a Changelog convention describes it as "a file which contains a curated, chronologically ordered list of notable changes for each version of a project". It recommends:
- Newest version at the top.
- One section per version with a release date.
- Changes grouped as Added, Changed, Deprecated, Removed, Fixed and Security.
- Written for humans, not generated by dumping commit logs.
Versioned changelogs usually pair with Semantic Versioning, where a major version signals breaking changes, a minor version adds backwards-compatible functionality and a patch fixes bugs.
For SaaS products without user-installed versions, the same idea becomes a product changelog: dated entries, categorised, on a public page.
Best for: anyone scanning history, such as developers checking when an API changed, customers wondering if a bug was fixed, or prospects judging how actively a product is maintained.
Release notes
Release notes focus on one release and its readers. They're often longer and more narrative:
- A summary of the headline changes and why they matter.
- How to use new features, with screenshots.
- Upgrade or migration steps and any breaking changes.
- Known issues.
Mobile app stores have a version of this ("What's New in this version"), and platforms like GitHub attach release notes to a tagged release. GitHub can even generate release notes automatically from merged pull requests, which is a helpful starting draft but usually reads like engineering notes, not customer communication.
Best for: announcing a release to the people affected by it, especially when they need to act.
Side by side
| Changelog | Release notes | |
|---|---|---|
| Scope | All notable changes, over time | One release |
| Format | Short, categorised, chronological entries | Narrative write-up, often with visuals |
| Audience | Developers, customers, prospects | Users of that release |
| Lifespan | Permanent, cumulative | Mostly relevant around launch |
| Typical home | /changelog page, CHANGELOG.md, in-app widget |
GitHub release, app store, email, blog post |
Do you need both?
It depends on what you ship:
- SaaS web app, continuous deployment: a product changelog is usually enough. Write a fuller blog post or email for big launches and link it from the changelog entry.
- Installed software, SDKs, APIs: keep a versioned changelog for developers and write release notes for major versions with migration steps.
- Mobile apps: store release notes are required; a public changelog helps users and support teams see history across versions.
Avoid writing everything twice
The pain point is duplication: engineers write a GitHub release, product writes the changelog, marketing writes the email. To keep it manageable:
- Write once, at the source. Draft the user-facing entry when the change ships, as part of the release.
- Make the changelog the hub. Every release note, email and social post links back to the canonical entry.
- Automate the copy. If you publish GitHub Releases, push them to your public changelog automatically. Nitrozen's GitHub Action turns a published release into a changelog entry, using the release name and body by default. There's a full walkthrough in automating your changelog from GitHub Releases.
- Edit for the audience. Automation gets content in place; a quick human pass turns "Refactor auth middleware (#412)" into "Sign-in is faster on slow connections".
Examples
Changelog entry (product):
Improvement: Bulk edit tags (2026-10-20) Select multiple items and add or remove tags in one step from the toolbar.
Release notes (versioned SDK):
v3.0.0: This release drops Node.js 16 support and renames
client.list()toclient.entries.list(). Update your calls before upgrading; the old method throws an error. New: automatic retries on 429 responses. Fixed: timeouts were ignored when set to 0.
Where Nitrozen fits
Nitrozen handles the changelog side: a hosted public page (on your own domain with paid plans), an embeddable in-app widget, Markdown entries with New, Improvement, Fix and Announcement badges, and automation through a REST API, SDKs, a GitHub Action and an MCP server for AI assistants. Your release notes can live wherever they make sense, and point back to one up-to-date history.
New to writing entries? Start with how to write a changelog users actually read.