# What is Release Notes?

Release notes are the per-release subset of a software product's changelog, written for the audience consuming a specific version — typically users of a SaaS product or developers integrating with a library. Each release notes entry covers one version's changes: what's new, what's improved, what's fixed, and any breaking changes or migration steps. The same release often generates both an engineering-flavored entry (terse, version-keyed, on GitHub Releases) and a customer-flavored entry (richer, user-focused, on a hosted product page).


## Example

The notes attached to a `v2.3.0` GitHub Release for an open-source
library are release notes for that one version. A SaaS product's
weekly "What's new" email or in-app widget update is also release
notes — same content shape, customer-flavored audience. Together,
a series of release notes entries forms the product's changelog.

## Why it matters

Release notes are the moment your shipped work becomes visible to
the people who pay for it. Without them, features go unnoticed,
support tickets repeat questions about things that already exist,
and users assume the product is stagnant. Good release notes turn
every release into a touchpoint — a small but consistent signal
that the product is alive and that you ship.

## More context

The biggest practical question with release notes isn't "what do they include?" — it's "who am I writing for?"

**Engineering-flavored release notes** live on GitHub Releases, in `CHANGELOG.md` files in the repo, and in package-manager metadata. The audience is other engineers — contributors, integrators, downstream library consumers, automated tools like Dependabot and Renovate. The voice is terse and reference-style. PR titles and commit hashes are appropriate. The reader will follow links to diffs if they want details.

**Customer-flavored release notes** live on your hosted product page, in your in-app widget, in subscriber email, and sometimes in your "what's new" announcement carousel. The audience is the people who use the product — operators, designers, marketers, end users who aren't engineers. The voice is friendly and explanatory. PR titles and commit hashes are noise. The reader wants to know "what changed in my world" — not "what changed in your codebase."

The same release event usually warrants both — written for different audiences. Tools like [Herald](/) read your merged GitHub PRs to draft the customer-facing version automatically AND publish back to GitHub Releases for the engineering audience, so the two surfaces stay in sync without copy-paste. See [Herald and GitHub Releases](/guides/herald-and-github-releases/) for the bidirectional flow.

For the practical "how to write release notes that users actually read" piece, the [release notes guide](/blog/how-to-write-release-notes/) walks through structure, voice, and the most common mistakes. For the related question of whether what you're writing is a changelog or release notes specifically, see [changelog vs release notes](/glossary/changelog-vs-release-notes/).

## Related terms

- [Changelog](/glossary/changelog/)
- [Changelog vs Release Notes](/glossary/changelog-vs-release-notes/)
- [Conventional Commits](/glossary/conventional-commits/)
- [Breaking Change](/glossary/breaking-change/)

Deeper guide: [How to write release notes users actually read](/blog/how-to-write-release-notes/)

Category: Changelog Fundamentals
Last reviewed: 2026-05-28