Changelog vs release notes: what’s the difference?

The two terms get used interchangeably, but they're different documents with different jobs. Knowing which one you're writing makes both easier.

The short answer

• A changelog is a continuous, public timeline of user-visible changes — one stream, newest first, spanning every release. Its job is to answer "what's been happening with this product?" at a glance.
• Release notes are a per-version document — everything in v2.3.0, often with context: upgrade steps, known issues, deprecation windows, sometimes marketing framing. Their job is to answer "what do I need to know before/after upgrading to this version?"

When the distinction matters

It matters when your users choose when to upgrade — installed software, APIs with versioned SDKs, self-hosted tools, mobile apps pinned by app-store review. Those users need release notes: a self-contained document per version with migration steps and known issues. We have per-platform playbooks for the big ones: app stores, desktop apps, CLIs and libraries, and firmware.

It barely matters for continuously-deployed products — SaaS, web apps — where everyone is always on the latest version. There is no "version" for users to reason about, so a well-kept changelog is your release notes.

One source, two documents

If you need both, don't write things twice. The sustainable pattern:

• Write each user-visible change as a changelog entry at the moment it ships (or as a draft just before).
• At release time, your release notes are those entries grouped by version, plus the per-version extras: upgrade instructions, known issues.
• Automate the mirror: if your releases live on GitHub or GitLab, a release webhook can republish them to your public changelog so the two never drift apart.

The same one-source idea extends to other surfaces — see announcing a new feature across channels.

What either document must never do

• Bury breaking changes below the fold (how to announce them properly).
• Say "various bug fixes and improvements" and nothing else. If it's worth a release, it's worth one honest sentence.
• Go silent. A dead changelog or a missing release-notes page reads as a dead product.

Where Wakelog fits

Wakelog is a free hosted changelog with the "one source" workflow built in: post entries from your terminal or CI, mirror GitHub/GitLab Releases automatically via webhook, tag entries so readers can filter, and give users a page, RSS feed, and in-app widget. If you keep per-version release notes on GitHub, the webhook keeps your public changelog in sync for free.

Start a free changelog   Next: how to write a changelog →

Related guides

• What is a changelog? A plain-English definition (with examples)
  The definition, a real example, how a changelog differs from a commit log, release notes, and a roadmap — and the three-step way to start one.
• Docs vs changelog: what each one is for (and how to keep them in sync)
  Docs answer “how does it work now?”; the changelog answers “what changed since I last looked?” They’re different documents with different tenses — and every behavior change has to touch both. The sync rules that keep either one from rotting.
• How to write a changelog (with examples)
  Structure, tags, cadence, good vs bad entries, and automation — everything you need to keep a changelog people actually read.

Last updated 2026-07-28 · All guides