Release Notes: How to Write Them, With Real Examples
Shayan, Founder21 min read

Release notes are the short, dated write-up a software team publishes when a change ships, telling users what's new, what changed, what was fixed, and whether they need to do anything about it.
Nobody sits down intending to write useless release notes. What usually happens is that the build is finished, an app store form or release script is waiting on a required text box, and the person pushing the button didn't write every pull request in the release. Someone in Slack says, "Just put bug fixes and improvements so we can get the build out," and that placeholder becomes the public record of the update.
Even teams with dedicated writers fall into the same habit. On October 26, 2026, Slack shipped version 4.53.269 of its Mac app. Its release notes read, in full:
We don't have anything in particular to call out for this release, but we thank you for staying up to date all the same.
Two months earlier, the note for version 4.52.155 opened with "Nothing major to report this week. Nothing minor to report either, as it turns out." That exact paragraph sat on version 4.51.191 two weeks before that, word for word.
Below is how teams like Stripe, Linear, Supabase, and Obsidian write release notes that users actually read, along with a template you can copy, three side-by-side rewrites of real updates, and the rules for the App Store and Google Play.
What are release notes?
Release notes explain what changed in a software update from the perspective of the person using the product. If a feature was added, a setting moved, an API field changed, or a bug stopped crashing a screen, the release note is where a customer checks to see if the update affects their work.
In everyday SaaS, "release notes" and "changelog" usually name the exact same page. Linear calls its updates page a changelog, Figma calls it release notes, Notion calls it releases, and GitHub publishes its changelog on its blog. Where teams do keep the two documents separate, the split is the one Keep a Changelog draws in its 2.0.0 specification:
A changelog is the complete, ongoing record: every notable change, across every version, kept in one file in the repository and written plainly for anyone. Release notes are an announcement for a single release: a curated selection of its headline changes, often with upgrade steps and a marketing voice, published when that version ships.
If you publish one dated entry per update on a public web page, you're writing both at once, and your users won't care which word sits in your navigation bar. If you also keep a CHANGELOG.md file inside a git repository, that file follows repository conventions while your public page is written for customers.
One outdated definition is worth ignoring right away. Wikipedia still lists twelve formal sections for a release note, including steps to reproduce, support impacts, and legal disclaimers. That outline describes an enterprise bug report from the era when software shipped on CD-ROMs and patches required a maintenance window. Modern software teams don't write release notes that way, and you don't need any of that ceremony.
Who reads release notes, and why
Bring up release notes in an engineering meeting and someone will inevitably say, "Nobody reads them anyway."
People don't curl up with release notes for fun, and they don't read them to be sold to. As a well-known Stack Overflow answer put it, users read them to "determine if they should go to the trouble of installing an incremental upgrade, or wait until the next release because this one doesn't add any features they need or fix any bugs in features that they were using."
Picture the person opening your release notes. They have your product open, they see an update prompt or notice a button isn't where it was yesterday, and they want to know in ten seconds whether anything changed for their workflow. On the Writing Stack Exchange, the highest-voted answer on release note tone stated the rule plainly:
Release notes should describe what changed as seen by the users. ... Release notes aren't a sales vehicle.
Depending on what you build, three kinds of readers show up on the page. End users want to know what they can do today that they couldn't do last week, and whether something they rely on moved. Admins and buyers look for changes to permissions, billing, or data handling that they need to explain to their own teams. Developers want the exact endpoint, parameter, or flag that changed, what replaces it, and how to upgrade without breaking production.
Because those readers want different levels of technical depth, teams often ask whether they should maintain separate release notes for different audiences. In practice, maintaining two parallel sets of notes doubles the writing work and guarantees one of them falls behind. Write one clear set of release notes for the people who use the product. When a release includes breaking changes for developers, put the step-by-step migration guide in its own document and link to it from the main entry. As one engineer on Hacker News put it: "+1 on separating 'how to upgrade' due to breaking changes from 'what's new'. A dedicated BREAKING.md / MIGRATIONS.md is a really good idea."
For everything that stays in the main release note, the accepted answer on Software Engineering Stack Exchange is the best filter: "A change log should tell end users why they should upgrade, not what changed in the code."
Release notes format and template
A useful release note answers what changed, when it shipped, and what the reader needs to do about it, while linking back to the customer request that prompted the work.
If you're setting up a house format for your product's release notes, put the parts in this order:
- A title that names the biggest change. Write
Priority inbox, notOctober updateorv2.4.1. Readers scan titles to decide whether to stop scrolling, and a title that saysBug fixestells them to skip the post. - The date on every entry. Customers check dates to see whether a product is actively maintained and whether a fix went out before or after they ran into a bug. Spell the month out or use ISO format like
2026-10-29, and keep it consistent across every post. - A version number, if your users install versions. Desktop apps, mobile apps, libraries, and versioned APIs need version numbers so users can check which build they have installed. Continuous web apps like Linear, Figma, Vercel, Supabase, and Cursor skip version numbers altogether.
- What's new, in one short paragraph per change. Explain what the user can do now, and state what it was like before. That "Previously..." sentence is the single most useful habit in the examples below.
- Improvements and fixes as one-line entries. Each line should name the screen or feature that changed and the symptom the user experienced.
- Breaking changes and required actions at the top. If the reader needs to update an API call, reinstall a desktop app, or change a setting, label it above everything else in the entry.
- Links to the docs and the original request. Point to the help article for setup details, and link the feature request the update answers so voters can see their feedback turned into shipping code.
Leave out internal refactors, issue tracker IDs, raw git commit lists, and anything a customer cannot see or feel. As another accepted answer on Software Engineering Stack Exchange notes, "Commit messages in a version control repository have a different audience than change logs."
Here is a clean Markdown template you can copy for a standard product release:
# [Title naming the biggest change in the user's words]
[Date] · [Version number, if your product uses one]
**Action required:** [What the user needs to do, or remove this line if nothing breaks.]
[What you can do now, in one or two sentences.] Previously, [what you had to do before, or what the old limit was].
Available on [all plans / specific plans]. [Where to find it or how to turn it on.]
Built from [this customer request](https://feedback.example.com/p/request-slug) · [Read the docs](https://docs.example.com/feature)
## Improvements
- [Feature or screen]: [What is faster, clearer, or easier to use]
## Fixes
- [Feature or screen]: Fixed an issue where [the symptom the user saw]For weekly agile roundups, bug-fix patches, breaking API changes, UI renames, or App Store updates, you can copy any of the six specialized release notes templates built for those releases. And if you maintain a CHANGELOG.md file inside a repository, Keep a Changelog's six standard headings, Added, Changed, Deprecated, Removed, Fixed, and Security, with an Unreleased section at the top and YYYY-MM-DD dates, remain the standard convention.
Real release notes examples worth copying
The easiest way to see why some release notes work is to look at how real products handle five common updates: an API change, a major feature, a limit increase, a menu rename, and a security or bug fix.
When Stripe shipped API version 2026-09-30 and made subscription trial offers generally available, the entry opened with two sentences:
Adds Trial Offers for subscriptions, which define reusable free or paid introductory pricing for individual Subscription Items, each with their own price and billing period. Previously, a subscription used a single trial period for the entire subscription.
The first sentence says what the feature does, and the "Previously" sentence explains what it replaces. Stripe's changelog also labels every entry Breaking or Non-breaking, splits the detail page into What's new, Impact, per-SDK Changes, and Upgrade steps, and links straight to the API reference. A developer checking whether an upgrade affects their billing code gets the answer immediately.
For a user-facing SaaS feature, look at how Linear announced its Priority inbox on September 3, 2026:
An active workspace can create a significant amount of notifications each day, and until now your inbox treated them all the same. The new Priority tab separates what needs your attention from what can wait, so something like a review blocking a release never gets buried.
It starts with the everyday annoyance, introduces the change, and gives one concrete example of a review blocking a release. Nothing in the paragraph reads like ad copy, and even a user who hasn't set up inbox rules yet understands why the tab exists. Underneath the main write-up, the same entry lists 26 smaller improvements and 16 bug fixes as one-liners so power users can scan the details.
GitHub uses that same now-and-previously rhythm even on minor updates, like this September 11, 2026 note on profile badges:
Your GitHub profile now displays the highest tier you've earned for achievements with multiple levels. Previously, profiles could display the first tier earned, even after you had progressed to a higher level.
When an update simply raises a quota or a technical limit, you don't even need a paragraph. Vercel ships several updates a day, and its October 28, 2026 index entry for its container registry is just a headline and one sentence:
Vercel Container Registry now supports 2 GB compressed image layers.
Push compressed image layers up to 2 GB, up from 500 MB.
It states the new number and the old number, then gets out of the way.
UI renames and navigation moves are easy to overlook when writing release notes, yet they cause instant confusion when a user clicks a bookmark or follows an older tutorial. Look at how Supabase handled a dashboard rename on September 21, 2026:
Database > Replication is now Database > Pipelines. Existing Replication URLs redirect to the new location. No API or pipeline behavior has changed.
In three short sentences, it gives the old path, the new path, and the two reassurances every developer wants: existing links still work, and nothing in production changed.
Finally, when a release fixes a security vulnerability or a specific crash, the note has to tell the user whether they are affected and what to do next. Obsidian's desktop 1.14.5 release note on October 22, 2026 leaves zero ambiguity:
This release updates Electron from 43.7.5 to 43.8.3, which includes several important security fixes. Download Obsidian from our website and reinstall the app.
Apple's iOS 27.0.1 release note does the same job for a hardware-specific bug:
This update provides bug fixes for your iPhone, including fixes for the following issues: iPhone 18 Pro and iPhone 18 Pro Max may unexpectedly restart when Face ID fails to authenticate
It names the exact devices, the symptom, and the trigger. Anyone whose phone restarted during Face ID knows right away that this update fixes their problem.
Release notes examples to avoid
Bad release notes usually fail in one of two ways: either they try to be clever while saying nothing, or they paste the same generic sentence on every build for two years.
We already saw Slack's Mac release notes in the opening. Slack's iOS app takes the same approach with slightly more words. Here is the full note for version 26.10.40 on October 28, 2026:
We tweaked some things too small to notice or too difficult to explain. We'll return you to your regular, more interesting types of release next time (we hope).
YouTube's iOS update on October 27, 2026, version 21.43.5, goes for a one-liner instead:
Fixed bugs, improved performance, took the afternoon off.
The other failure mode is permanent copy-pasted boilerplate. If you check the App Store version history of major consumer apps in late October 2026, you'll see the exact same lines repeated across dozens of consecutive releases. Spotify's 9.1.94 note from October 23, 2026 reads:
We're always making changes and improvements to Spotify. To make sure you don't miss a thing, just keep your Updates turned on.
Instagram's 453.0 update from October 26, 2026 says "Performance optimizations and stability improvements for a smoother, more reliable experience," and WhatsApp's 26.42.74 note from the same day says "We update the app regularly to fix bugs, optimize performance and improve the experience. Thanks for using WhatsApp!" None of these names a single screen, feature, or bug. As one Hacker News commenter remarked about updates like these, they are "informationally identical to a release note that just says 'New release.'"
Even teams that care deeply about their web changelogs treat the mobile store field as an afterthought. Linear's web post for Priority inbox explains the feature thoroughly and itemizes 42 improvements and fixes, while Linear's App Store update for the same app simply reads "Bug fixes and minor improvements". Notion's web releases page is detailed and specific, while its iOS App Store note is "Bug fixes and performance improvements."
What if a release genuinely only contains bug fixes and speed improvements? A commenter in a June 2026 Hacker News thread on writing release notes for non-technical users gave the exact reason to still name them:
What bugs were fixed? What was made faster? If I was experiencing some bugs or slowness, I would be happy to see my issue may have been addressed in the release. If it says the issue was fixed, and I still see an issue, that's a reason to send some feedback again.
When you fix a bug, name the broken behavior the user saw. The people who ran into that bug are the ones checking the release note to see if they can stop using their workaround.
How to write release notes: three real rewrites
The quickest way to get a feel for editing release notes is to take real updates from well-known products and trim the filler while keeping every fact from the original.
1. Cut the costume drama so the fix is easy to find
Here is a bug fix from Slack for iOS, version 26.09.10, published on September 2, 2026 under Bug Fixes:
Forwarded emails were crashing the party in disguise, showing up in channels wearing the icon and name of totally unrelated apps. Turns out that's not appropriate business attire. The masquerade is over, and these emails will now be clearly labeled as themselves.
Here is the rewrite:
Fixed: forwarded emails in channels showed the icon and name of an unrelated app. They are now labeled as emails.
Unlike Slack's Mac notes, the original entry here actually describes a real fix. The problem is that the two party-costume jokes bury "forwarded emails" and "unrelated apps", which are the exact words an admin or user experiencing the bug is scanning the page to find.
2. Replace vague filler with what actually works
Here is how Discord announced Better Markdown Previews on October 22, 2026:
When you upload a Markdown (.md) file, you'll now see the file rendered all nice and neat and pretty instead of with a bunch of symbols. This includes tables, formatting, all that good stuff. Totally great for when you're doing a casual Sunday-night sharing READMEs with your friends.
Here is the rewrite:
Uploaded Markdown
.mdfiles now render as formatted text, including tables, instead of showing raw symbols.
Discord's casual voice is part of its brand, and there's nothing wrong with keeping a light tone. What hurts the note is "all that good stuff", which sits in the exact spot where a user wants to know whether code blocks, task lists, or headings actually render.
3. Strip internal ticket numbers from public notes
Here is an entry from 1Password for Mac, version 8.12.33, published on August 12, 2026:
We've fixed an issue where the 1Password browser extension in Safari couldn't connect to the 1Password app. !40819
Here is the rewrite:
We've fixed an issue where the 1Password browser extension in Safari couldn't connect to the 1Password app.
The sentence itself is already great: it names the Safari extension, the symptom that it couldn't connect, and the fix. The !40819 merge request number at the end is only useful to 1Password's own engineers, and on a public release page where customers can't click it, it's just visual noise.
A simple process for writing the entry
Those three edits follow the same six rules:
- Start from what shipped to users, not from the commit log. Pull from your completed customer requests, closed bug tickets, or merged pull requests.
- Write the sentence a user would say to a coworker. Start with
"You can now..."or"Fixed:...", and add"Previously,..."whenever the old behavior helps explain the change. - State whether the reader has to do anything. Supabase's
"No API or pipeline behavior has changed"and Obsidian's"Download Obsidian from our website and reinstall the app"both answer the reader's next question before they have to ask support. - Cut any sentence that doesn't name something in the product. Every line should mention a screen, a setting, an endpoint, or a workflow. As one Software Engineering Stack Exchange answer warns, "every additional sentence loses another 10% of the readers. So you must strictly prioritize what your current users need to know about the release."
- Put the biggest change in the title and the first sentence. Most readers never scroll past the top of the entry.
- Read it back as the customer who asked for the feature. If they wouldn't recognize their problem in your description, you're still describing the code rather than the change, which is the main habit behind writing changelogs people read.
Can you generate release notes from commits?
Almost every engineering team eventually asks why anyone writes release notes by hand when Git already has every commit message and pull request title. Nobody wants to spend Friday afternoon pinging engineers in Slack to ask, "Wait, is this flag live for customers or still behind a config?"
The catch is that a git commit and a release note are written for two different people. As a Hacker News commenter explained in 2022:
The purpose of a git commit message is to answer the question "why does this commit exist?" ... The changelog, on the other hand, answers the question "why does the customer care about these changes?"
Keep a Changelog 2.0.0 makes the same point:
Do not use a list of commits as a changelog. It is full of noise: merge commits, unclear messages, internal changes. A commit records a step in the source code. A changelog entry records a notable difference, often across several commits, written for the people who use the software.
Automated tools are still helpful as long as you treat their output as what Keep a Changelog calls "raw material at best". GitHub's "Generate release notes" button compiles what GitHub's documentation describes as "a list of merged pull requests, a list of contributors to the release, and a link to a full changelog", grouped by label if you configure .github/release.yml. Tools like release-please, semantic-release, git-cliff, and conventional-changelog parse Conventional Commits such as feat:, fix:, and BREAKING CHANGE: to assemble a categorized list and calculate the next semantic version number.
For an open-source CLI or library, a generated list only reads well if contributors write commit messages for end users in the first place. On Hacker News, the maintainer of rclone described how he makes that work:
I try to encourage all contributors to make the first line of their commit message be something a user would like to read in the changelog. Instead of
fixed nil pointer errorhavefixed crash when copying file to xyz backend.
A script pulls those first lines into a draft, and he then spends about an hour per release cutting the internal noise and grouping the entries. As Keep a Changelog 2.0.0 puts it, "machines can draft, but humans curate."
For a SaaS product, there is a much better starting point than git commits: the customer requests and bug reports you marked completed during the cycle. Those threads already describe the problem in the customer's own words, which gives you both the headline and the "previously" sentence without translating code changes back into English.
App release notes: App Store and Google Play rules
If you ship a mobile app, you have to deal with the release notes fields in App Store Connect and Google Play Console, and the two stores give contradictory advice on tone.
On Apple's App Store, the What's New in this Version field is "Limited to 4000 characters." App Store Connect hides the field on an app's first version and makes it "required for all subsequent versions." In the App Store Review Guidelines, section 2.3.12 states the rule on generic text:
Apps must clearly describe new features and product changes in their "What's New" text. Simple bug fixes, security updates, and performance improvements may rely on a generic description, but more significant changes must be listed in the notes.
Meanwhile, Apple's product page documentation encourages teams to "add call-to-action messaging that gets users excited about the update."
On Google Play, the release notes field allows "up to 500 Unicode characters per language", wrapped in language tags on separate lines:
<en-US>
Fixed: forwarded emails in channels showed the icon of an unrelated app.
</en-US>Google's content rule is two sentences, and the second one directly forbids what Apple encourages:
Inform users about recent updates made in your release. Do not use release notes for promotional purposes or to solicit user actions.
The simplest way to handle both stores without writing two versions is to write for Google Play's constraints first. Keep the text under 500 characters, lead with the one change that matters most, and skip promotional calls to action like "Tap to try it out" or "Leave us a review." That note will pass both Apple and Google unchanged.
Why do so many huge apps ignore Guideline 2.3.12 and paste "Bug fixes and improvements" every week? Partly because the field is mandatory on every build even when visible features are gated behind server-side flags, and partly because most consumers have automatic updates turned on and never visit the Updates tab. Neither excuse holds up if you build software where users care about their workflow.
A good mobile store note doesn't need to be long. Here is Bear's 3.0.3 update on the App Store from October 22, 2026, which comes in under 200 characters:
New: A new toolbar now appears when you're entering tags or wikilinks, or searching for notes. It makes it easier to move the cursor and type special characters.
Bug fixes and stability improvements.
It names the one visible improvement and where it shows up, then uses the generic line for the minor fixes underneath, which is exactly what Apple's guideline allows.
Where to publish release notes
Where you host your release notes depends on how customers use your product, and most teams combine a public archive with an in-app notification.
SaaS products like Linear, Figma, Vercel, and Supabase publish on a dedicated /changelog or /release-notes page on their website. Developer platforms and tools like Stripe and VS Code keep their release notes inside their documentation site so entries can link directly to API references and settings guides. Open-source libraries like Tailwind CSS publish on GitHub Releases alongside their repository CHANGELOG.md, while multi-platform apps like 1Password run a dedicated releases subdomain split by operating system.
Whichever home you choose, the page itself doesn't need fancy visual design. The best release notes pages are plain and predictable: they order entries newest first with a calendar date on every post, and they give each entry its own permanent URL so support and sales teammates can paste a direct link into a customer reply. Tagging posts by change type, such as New Feature, Breaking Change, or Bug Fix, or by product area lets a developer who only cares about the API filter out UI updates, while an RSS or Atom feed lets power users and customer Slack channels subscribe automatically, the way Linear, Vercel, Obsidian, and 1Password do.
Just remember that most active users log straight into your app and never visit your marketing website to check /release-notes. Discord surfaces its notes inside the app under Settings, and Linear lights up an in-app notification. Embedding an updates feed through an in-app feedback widget is the simplest way to put new releases in front of customers where they already work.
Write the release note from the requests you shipped.
Juno, the assistant in UserJot's changelog editor, drafts your release note from the customer requests you marked Completed, and links those requests right under the post. Free to start, with unlimited users.
From the customer request to the release note
The reason release notes feel like a chore at the end of a sprint is that the context is usually scattered across pull requests, Slack threads, and support tickets. When your feedback board, public roadmap, and changelog tool live in the same place, every request you complete during the week is already a release note half written: the title is what the customer asked for, and the "previously" sentence is sitting right in their original post.
On UserJot, marking a request Completed automatically emails everyone who posted, voted, or commented on it. When you open the changelog editor to write the release note, our editor assistant Juno reads the requests you completed since your last post along with their comments, and drafts the entry with the title, date, tags, and linked requests filled in. Her edits stay highlighted until you accept them, and once you publish, the post appears on your /updates page and inside your app through the widget. Publishing is included on every plan, including Free, with unlimited users.
Frequently asked questions
What is the difference between release notes and a changelog?
A changelog is the complete, chronological record of every notable change across every version of a project, while release notes are the announcement and upgrade summary for one specific release. In practice, most SaaS teams publish a single updates page with dated entries and use the two words interchangeably. The distinction matters mainly when you maintain a technical CHANGELOG.md file in a repository alongside a curated release notes page for customers.
How long should release notes be?
Make them as long as the list of changes a user can actually see, and no longer. A quota increase on Vercel's changelog is a title and one sentence, while a major Linear feature is a short paragraph followed by one-line improvements and fixes. Every extra sentence that doesn't describe a user-visible change costs you readers.
Who should write release notes?
Whoever can explain the change from the customer's perspective, which is usually a product manager, a technical writer, or the engineer who built the feature with one editor reviewing the release for a consistent voice. Commit messages and pull request titles are raw material for the writer, not finished copy for the customer.
How often should you publish release notes?
Publish whenever you ship a change that users can see. Teams that deploy continuously like Vercel and GitHub post short entries as features go live, while desktop and productivity apps like Raycast publish a weekly roundup. What matters most is writing the note while the release is fresh rather than trying to reconstruct a month of changes from memory.
What should you write when a release is only bug fixes?
Name the specific bugs that were fixed and the symptoms users saw on screen, rather than pasting "Bug fixes and performance improvements." A customer who ran into a Safari extension disconnect or a Face ID restart reads the release note specifically to find out whether their issue was resolved or whether they still need to report it.
Are release notes required on the App Store and Google Play?
Apple hides the What's New field on an app's initial 1.0 submission and makes it required on every update after that, with a 4,000-character limit. Google Play allows up to 500 Unicode characters per language wrapped in language tags like <en-US>. Writing a plain, specific summary under 500 characters with no promotional calls to action satisfies both stores at once.
Should you include internal bug IDs or commit hashes in release notes?
Leave internal ticket numbers and commit hashes off public SaaS and consumer release notes, since customers cannot click into your private issue tracker anyway. Only include pull request or issue links when you are publishing a developer changelog for an open-source repository where engineers genuinely read the linked code and discussion.



