Good release notes explain what changed for the person using the app. Start from the changes verified in the release, describe their visible effects, and leave upcoming work out of the update description.
I make Squatti, the NaguBuilds alarm app currently listed in the US App Store as Squat Alarm: Stop Snoozing. Use this worksheet while editing your own release notes. The example sentences below are writing exercises; the separately identified public notes come from the current store listing.
Apple's platform version reference describes the What's New field as a place for new features, improvements and bug fixes. Each line should help someone understand how the update affects them.
Turn a code change into a user-visible statement
A commit title is often written for another developer. It may identify a file, implementation detail or internal project name without explaining the result.
Before rewriting it, find out what actually changed. If a fix changes a date preview, determine which preview and under what condition. If the release improves support for larger text, identify the screens covered. Do not expand a small fix into a claim about the whole app.
Consider a hypothetical change to a next-alarm label. "Fixed date handling" gives the reader little information. "Fixed the next-alarm date shown after editing a one-time alarm" would be more useful if that exact behavior was changed and verified. This is an example, not a claim about a Squatti release.
Make one record for each candidate note
- Released change:
- Who will notice it:
- Previous visible behavior:
- New visible behavior:
- Conditions or screens covered:
- Evidence checked in the release being described:
- Candidate sentence:
- Words that promise more than the evidence supports:
Leave out internal identifiers from the public sentence unless they help users understand or report a problem. Keep enough detail in the private working record to trace the sentence back to the change.
If you cannot connect a proposed note to the release, hold the sentence. A feature being merged locally is not the same as its being included in the version customers receive.
Choose the details that affect use
Group related changes when that makes them easier to read. Keep a distinct fix separate if combining it would hide the condition the user cares about.
Squat Alarm's public 1.1.0 notes mention translation and local-currency improvements, larger text and VoiceOver support, subscription handling, and fixes involving alarm-date and reminder previews. Those are examples from the public store record, not a list of what a future version will contain.
A short update can be enough when the release has a small scope. Avoid adding "faster," "more reliable" or "easier" unless you can explain the improvement those words stand for.
Check the version boundary before publishing
Use the iPhone alarm app release checklist to organize the checks behind your notes. Compare the finished copy with the version being prepared. Check names, platform requirements and any feature availability mentioned in the notes. Revisit the copy if a change is removed from the release.
Read it once more without the working record beside you. Each sentence should explain a change a user could recognize. Add a limitation where omitting it would overstate the change, and remove anything that belongs to a future version.
You can inspect the current public example in Squatti's listing under Squat Alarm. For your own update, the completed worksheet should produce a small set of accurate sentences whose scope matches the release.