What is Release Notes?
Last reviewed May 28, 2026
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 for the bidirectional flow.
For the practical "how to write release notes that users actually read" piece, the release notes guide 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.
Related terms
Want to go deeper? Read How to write release notes users actually read.