What do release notes contain?
Release notes sit between the engineering work and the customer. Engineers ship code; release notes translate that code into consequences a user can understand. A good set answers three questions: what changed, why it matters to me, and what do I need to do.
Most release notes are grouped by type of change. New features come first, followed by improvements to existing behavior, then bug fixes. Many teams add sections for known issues, breaking changes, and deprecation notices so users are not surprised later.
Each note is tied to a specific version or date. Teams that use semantic versioning label the release with its number. Teams that ship continuously often date each entry instead and publish it as a product update.
Release notes can be public or internal. Public notes go to customers on a website, inside the app, or by email. Internal release notes brief support, sales, and success teams before the customer-facing version goes out.
Why do release notes matter?
Users cannot adopt what they do not know exists. When a feature ships silently, the team pays for the build but earns little of the value. Clear release notes turn shipped work into feature adoption.
They also cut support load. When a button moves or a workflow changes, users who read the notes understand why. Users who never saw an explanation file tickets instead.
For customer success, release notes are a renewal tool. A visible record of steady improvement gives account managers something concrete to show at every check-in. It also signals to prospects that the product is alive and maintained.
Inside the company, release notes align teams. Support learns what changed before customers ask. Marketing spots launches worth promoting. Product gets a shared record of what actually shipped and when.
Release notes examples
App store listings are the most familiar example. Every update to a mobile app on the Apple App Store or Google Play carries a "What's New" section. Slack became known for writing these in a playful, human voice rather than a list of ticket numbers.
GitHub publishes release notes for its own platform on a dedicated changelog site, grouped by date and product area. Open source projects hosted there also attach notes to each tagged version, often generated from merged pull requests.
Figma and Notion publish "What's New" pages that pair each entry with a screenshot or short video. Visual notes work well for design and productivity tools, where a change is easier to show than to describe.
For a wider set of formats, see these release note examples and our roundup of the best app release notes.
How to write good release notes
- Lead with the user benefit. Write "You can now export reports as PDF" rather than "Added PDF export module." State the outcome before the mechanism.
- Group by type of change. New, improved, fixed. Readers scan for the section they care about.
- Keep each entry short. One or two sentences per item. Link to documentation for detail.
- Show, do not only tell. Add a screenshot or a short clip for visual changes.
- Flag anything that requires action. Breaking changes, migrations, and deprecations belong at the top, not buried in a list.
- Keep a steady rhythm. A predictable release cadence trains users to look for notes.
- Publish where users already are. A public page plus an in-app widget and an email digest reaches more readers than any single channel.
- Automate the draft, not the judgment. Tools can pull merged tickets into a first draft. A human still decides what matters to customers. See how to automate release notes.
Our release notes best practices guide goes deeper on structure and tone.
Release notes vs changelog: what is the difference?
A changelog is the running log of every change, often terse and ordered version by version. Release notes are the narrative written for one release, with context and benefit. Many teams use a single page for both, and the two terms are often used interchangeably. The distinction matters most when the audience differs: developers want the log, customers want the story. See changelog vs release notes for a fuller comparison.
Common mistakes:
- Writing for engineers instead of users, with ticket IDs and internal feature names.
- Skipping small releases, so the page looks abandoned between big launches.
- Publishing only on a web page nobody visits, with no in-app or email delivery.
- Burying breaking changes below cosmetic fixes.
- Using marketing hype where a plain sentence would do.
How AnnounceKit handles release notes
AnnounceKit publishes release notes to a changelog page on your own domain and surfaces the same posts inside your product through an in-app widget with more than ten display modes. Posts can be segmented so each customer sees only what applies to them, and delivered as email digests or to Slack. AI post generation drafts a first version from your notes, and an official MCP server lets AI agents read and publish updates. Feature requests with voting and Jira sync, plus NPS surveys, close the loop after a release. Pricing is flat per project from $79 per month, with a 15-day free trial.