Release Notes vs Changelog: What's the Difference?

A changelog is a technical record of every change in a project, written for developers. Release notes are a curated summary of what matters to users, written in plain language. They serve different audiences and follow different formats. Many teams maintain both.

What a Changelog Is

A changelog lists every notable change to a project in reverse chronological order. It’s organized by version number and grouped by type: added, changed, deprecated, removed, fixed, security.

The format comes from Keep a Changelog, a widely adopted convention. Here’s what a typical entry looks like:

## [2.4.0] - 2026-01-20

### Added
- WebSocket support for real-time document sync (#342)
- Rate limiting on /api/publish endpoint (50 req/min)

### Changed
- Upgraded markdown parser from marked 9.x to 14.x
- Default theme font changed from System UI to Inter

### Fixed
- PDF export failing for documents with tables wider than page (#338)
- Auth token not refreshing when tab is backgrounded (#341)

### Security
- Patched dependency vulnerability in image processing library (CVE-2026-1234)

The audience is developers, contributors, and system administrators. People reading changelogs want to know exactly what changed and why, with links to issues and pull requests.

What Release Notes Are

Release notes tell users what’s new, what’s improved, and what to watch out for. They skip internal changes (dependency bumps, refactors, CI fixes) and focus on things users will notice.

Here’s the same release as a set of release notes:

# What's New in v2.4

## Real-Time Collaboration
You can now see changes from other editors as they happen.
Documents sync in real time when multiple people have the
same link open.

## Better PDF Export
Tables in PDF exports now wrap correctly instead of getting
cut off at the page edge. If you had trouble exporting
documents with wide tables, try again with this update.

## Updated Typography
We switched the default font to Inter for better readability
on screens. Your existing documents will use the new font
automatically.

## Breaking Change
If you use the API directly, note the new rate limit on the
publish endpoint: 50 requests per minute. Most users won't
be affected, but if you run automated publishing scripts,
you may need to add a delay between requests.

The differences are clear. No version number in the heading (users don’t think in semver). No issue links. No mention of the CVE patch or parser upgrade. Plain language descriptions of what changed and why it matters to the person using the product.

Side-by-Side Comparison

When to Use Each

Changelogs work best for:

• Open-source projects where contributors need to track changes
• Internal libraries consumed by other teams
• API products where developers are the primary users
• Compliance and audit trails that require a record of every change

Release notes work best for:

• SaaS products with non-technical users
• Mobile apps distributed through app stores
• Desktop software with automatic updates
• Any product where the audience cares about “what can I do now” rather than “what code changed”

Many teams write both. The changelog is generated semi-automatically from commit messages or PR labels. The release notes are written by hand, pulling from the changelog but rewriting for a different audience.

How to Write Good Release Notes

Good release notes follow a few patterns.

Group by category. Separate new features, improvements, bug fixes, and breaking changes into distinct sections. Users scan for what’s relevant to them.

Use plain language. “Documents now load 40% faster” is better than “Implemented virtual scrolling with intersection observer for document list rendering.” Describe the outcome, not the implementation.

Mention breaking changes early and prominently. Put them in their own section with a distinct heading. Explain what changed, who’s affected, and what they need to do.

Include visuals when possible. A screenshot of a new feature or a short GIF showing a workflow change communicates more than a paragraph of text.

Link to documentation. If a new feature needs explanation, link to the docs page rather than trying to explain everything in the release notes.

Keep it scannable. Short paragraphs. Bold the feature name. Use headings. Most readers will skim.

Automating Changelogs

Generating changelogs by hand is tedious. Most teams automate it.

Conventional Commits is a commit message format (feat:, fix:, chore:) that tools can parse into changelog entries. Tools like conventional-changelog and release-please generate markdown changelogs from your Git history.

# Example using conventional-changelog
npx conventional-changelog -p angular -i CHANGELOG.md -s

GitHub Release Notes has a built-in feature that auto-generates notes from merged PRs. Configure it with .github/release.yml to group PRs by label.

Neither approach produces good release notes for end users. Automated output is too technical and too granular. Use automation for the changelog, then write the release notes by hand.

Publishing with MDtoLink

Both changelogs and release notes are markdown documents. MDtoLink can publish either one to a shareable URL.

# Publish your changelog
mdtolink CHANGELOG.md

# Publish release notes for a specific version
mdtolink release-notes-v2.4.md

This is useful for sharing release information with stakeholders who don’t have access to your GitHub repo, or for sending a clean link in an announcement email instead of attaching a file.

For more on publishing changelogs, see Changelogs with MDtoLink. For release notes workflows, see Release Notes with MDtoLink.