How to write release notes people read (and how a changelog differs)
Lead with the one change a user will notice, write it as what they can now do, show that part of the screen, and describe each fix by what the user saw go wrong.
Chris Raroque
·
To write release notes people read, lead with the one change a user will notice, write it as what they can now do, show that part of the screen, and describe each fix by what the user saw go wrong. The template below puts those in order, and eight steps explain each part.
The examples are real notes from Amy, the food journal I build. Its App Store version history is public, so each note quoted here can be checked against Amy’s App Store page. After the steps, one update, version 1.75, is taken through the three places it gets written. Where a step has a guide of its own, the link is in the step.
A release notes template you can copy
The App Store’s What’s New is a text field, so it gets the headline and the list. A changelog page, an email or an in-app note has room for all of it.
Release notes vs a changelog
A changelog is the full record: every notable change in every version, usually kept in a CHANGELOG.md file in the repository. Release notes announce one release to the people who use it: a few changes, chosen and written for them, often with an image, published where they will see it.
Changelog | Release notes | |
|---|---|---|
Written for | Developers, contributors and anyone who needs the full record | The people who use the product |
Covers | Every notable change, in every version | The changes this release’s users will notice |
Lives in | CHANGELOG.md, or a page that mirrors it | The App Store’s What’s New, a product updates page, the app itself, email |
Ordered by | Type of change | What matters most to the user |
Images | Rare | Usually one, for the headline change |
Keep a Changelog 1.1.0, the version keepachangelog.com’s home page still leads to and the format most CHANGELOG.md files follow, defines a changelog as a curated, chronological list of the notable changes in each version. It groups entries under six types (Added, Changed, Deprecated, Removed, Fixed and Security) and opens its guiding principles with “Changelogs are for humans, not machines.” Its 2.0.0 page, published June 7, 2026, answers this exact question: the changelog is the complete record, and release notes are drawn from it and shaped for the announcement.
In practice the names blur. Many products call their public updates page a changelog when it is really a series of release notes: one post per release, written for users. Amy is one of them: the button in its Settings says Changelog, and it opens Amy’s updates page, where each 2026 post has a headline such as “Make Amy yours” and ends by naming the Amy version it arrived in. What matters is which reader a page serves. If it is the people who use the app, write it as release notes. Changelog examples shows eleven real update pages, dated and annotated, on both sides of that line.
The App Store has its own field for this. Apple’s help for What’s New in this Version describes it as the changes in the version, such as new features, UI improvements or bug fixes, limited to 4,000 characters, required for every version after the first, and localizable.
How to write release notes, step by step
1. Pick the one change a user will notice
Rank the release by what changes for the person using the app, not by how much work it took. One change leads, and everything else goes in a short list after it. Amy 1.72 (July 25, 2026) has this shape: the whole note is about one thing, “Customize your goal bar your way,” followed by what that means (drag goals to reorder them, choose which appear, control how many show in the compact bar).
The one exception goes above the headline: anything the reader has to act on, such as a feature that was removed or a setting they need to change. Say what changes for them and what to do. Keep a Changelog makes the same point for changelogs: if you record nothing else, record deprecations, removals and breaking changes.
If nothing a user can see changed, say that in one plain line instead of dressing it up.
2. Write the headline as what the user can do now
Amy 1.75’s note opens with “You can now share food photos with Amy directly from other apps.” In Amy’s code the feature is a share extension, and the note never says so. It names something people already do (share a photo) and what is new (Amy is now a place to send it).
A quick test: the headline should finish the sentence “You can now…” or “Amy now…” in words from the app’s own interface. If it only works as a feature name, such as “Share extension”, rewrite it.
3. Say where it is and how to use it
The headline says what. The next sentence says how, with the exact labels. For 1.75: open a food photo in Photos, tap Share, then Amy (if Amy isn’t in the row, tap More). Copy labels from the app, capitals included, so a reader can match them on screen.
In the App Store the headline may be enough. On a changelog page, in an email or inside the app, readers want the steps.
4. Show the part of the screen that changed
Before: the raw capture of the iOS share sheet with Amy in the app row, taken from the iOS Simulator on September 16, 2026 with Moonjar, our screenshot app, which sets the clean 9:41 status bar. It is shown whole on a plain background; nothing else is changed.
After: the same capture with the changed row lifted and the rest dimmed, styled with Moonjar, our screenshot app, on September 18, 2026. Photo by Bernd Dittrich on Unsplash.
A raw screenshot gives every control the same weight, so the reader has to hunt for the change. In the share sheet above, Amy is one icon in a row of four, with the photo above it and more actions below it. Lift the row that changed (or crop to it), dim the rest, and keep the status bar clean. Use the same look for every entry, so a page of release notes reads as one set. How to make a good product screenshot covers each of those choices with before and after pairs.
Use a still for a new button or setting. Use a short clip, a few seconds with the waiting cut out, for a new flow. In many changelog tools a video has to be a link to a host such as YouTube or Loom, while a GIF plays inline; turning a Mac screen recording into a small GIF shows how to keep one under the usual size limits.
When the interface changes again, leave the old entry’s image alone. A release note records what that version looked like; your help center is the place that should show the current screen.
The After image was made with Moonjar, our screenshot app (in early access, Mac only), which draws the iPhone and runs the lifted row slightly past the phone’s edges. You can get the same result by hand in a design tool: crop, dim everything but the row, and set the row on a card. Here is what Moonjar makes, and early access if you want to try it.
5. Describe each fix by what the user saw
Two of Amy’s notes about barcode scanning show the difference:
1.57 (April 16, 2026): “Barcode scanning and other bug fixes!”
1.69 (July 15, 2026): “Duplicate barcode scans now keep each serving’s calories and macros separate. The barcode scanner flashlight now stays on without pausing the camera. This update also includes reliability improvements.”
The first doesn’t say whether barcode scanning is new or fixed, or what the other fixes were. (It was new: Amy’s updates page announced “Scan labels and barcodes” the same day.) The second tells you what was wrong and what happens now, so someone who hit the problem knows it is gone. Amy 1.58 (April 17, 2026) adds a third part, what the user should expect next: Apple Health sync settings could turn off on their own, the toggles now stay as set, and Amy will say if iOS permissions need attention.
A more recent one does it in a single sentence. Amy 1.76 (September 5, 2026): “Saved meals now load reliably after a fresh launch, so they’re ready when you open Amy.” A user who opened Amy to an empty list of saved meals recognizes the problem, and learns it’s gone, without the word “bug”.
The pattern: what went wrong, in the user’s words; what happens now; anything they need to do.
6. List the rest briefly, and leave out what users can’t see
After the headline, group the smaller changes under plain labels such as New, Improved and Fixed. Leave out what a user can’t notice: refactors, dependency updates, build changes, ticket numbers and internal code names. Those belong in the changelog or the commit history.
A general line such as “reliability improvements” is fine once, at the end, when it is true. Amy 1.75 does this: the headline, then one fix in a clause, then the general line. It should never be the headline.
7. Fit the note to where it will be read
Where | What fits | Length |
|---|---|---|
App Store What’s New | The headline, then the list, as text | Up to 4,000 characters (Apple’s limit). The 25 notes on Amy’s App Store page on September 18, 2026 ran from 24 to 388 characters. |
Changelog or product updates page | Headline, how to use it, image, version, date, a link to each entry | As long as the steps need |
Inside the app | The headline change, its image, a button to try it | One screen |
The headline, one image, a link to the full entry | A few lines | |
CHANGELOG.md | Every notable change, grouped by type, with the date | Complete |
The 4,000-character limit is a ceiling, not a target. App Store release notes covers that field in detail: how much of a note shows before the “more” link, the Promotional Text field you can change without a new version, and current notes from four apps.
8. Give every version its own note and date
Amy 1.61, 1.62 and 1.63 (June 12, 15 and 16, 2026) carry the same four-line note, and 1.65 and 1.66 share another. Reading the history, you can’t tell what 1.63 changed from 1.62. When a version only fixes the one before it, give it a line of its own, for example “Fixes a crash, introduced in 2.3, when opening a shared list.”
Date every entry. Keep a Changelog recommends writing dates in the file as year, month, day (2026-09-02): the order runs from the largest unit to the smallest, and it can’t be confused with regional formats that swap the month and the day. On a page for users, a written date such as September 2, 2026 reads more easily.
One update, written for three places
Amy 1.75 went out on September 2, 2026. Here it is as it shipped, then as a changelog page entry and as a CHANGELOG.md entry. Amy’s updates page has no post for 1.75, so the last two were written for this article, from the public note and the labels in Amy 1.75.
In the App Store, as it shipped
You can now share food photos with Amy directly from other apps. This update also fixes API key permissions for connected tools and includes reliability improvements.
It is 166 characters. The headline is a capability in the user’s words, the fix is one clause, and the general line comes last. What a text field can’t do is show where Amy appears or what happens after you tap it. The changelog page entry adds that.
On a changelog page
Share a food photo to Amy from other apps
September 2, 2026 · Version 1.75
You can now send a food photo to Amy from the share sheet. Open the photo in Photos, tap Share, then Amy (if Amy isn’t in the row, tap More). Amy reads the photo, shows the calories and macros it estimated, and lets you choose Log Today or Save as Meal. It works with one photo at a time.
Also in 1.75
Fixed: API key permissions for connected tools.
Reliability improvements.
Under the text goes one image: the After image from step 4, which shows exactly where Amy now appears.
In CHANGELOG.md
“Reliability improvements” is left out on purpose. A changelog lists notable changes, and a line that names none adds nothing to the record. If the reliability work was specific, name it under Fixed.
If you keep CHANGELOG.md in a git repository, the first draft of an entry like this can come from your commits: a free Claude Code skill for changelog entries drafts one in this format for you to edit, and AI changelog generators compares the tools that draft from commits, pull requests or tickets. Either way, a person still picks the headline and rewrites the fixes in the user’s words; steps 1 and 5 are the parts a tool can’t know.
Before you publish
Every button and screen name matches the app, capitals included.
The image shows the changed part and nothing private. Use demo data.
The version number and date are right, and the note is not a copy of the previous one.
The App Store text is 4,000 characters or fewer, and localized if your listing is.
No ticket numbers, code names or library names.
Each entry on a changelog page has its own link, so people can share one change.
Then publish it where your users will see it. If your site is built in Framer, how to create a changelog in Framer CMS builds the page with a link for every entry. If you’d rather use a hosted tool with an in-app widget, the best changelog tools compares them on how they show screenshots, GIFs and video.
The notes quoted here are from Amy’s App Store Version History and Amy’s updates page, read on September 18 and rechecked on September 19, 2026. The share-sheet capture was taken with Moonjar in the iOS Simulator on September 16, 2026, and the After image was styled from it with Moonjar on September 18, 2026. The cover shows Amy’s Settings, captured and styled the same way, over a photo by Ch Photography on Unsplash. The text was drafted with AI assistance.