App store release notes: writing "What's New" text people actually read

Mobile release notes are the strangest corner of change communication. The text ships inside a store listing you don't fully control, under character limits, next to a version number most users will never consciously install — and the default the industry has converged on is the single least informative sentence in software: "Bug fixes and performance improvements." This guide covers the actual constraints on iOS and Android, why that sentence costs more than it saves, and a setup that works with release trains instead of against them.

The constraints, concretely

  • App Store (iOS): the "What's New" field allows up to 4,000 characters, but it is tied to a version — changing it later generally means submitting a new build through review. Only the first few lines show on the product page and in the Updates list before a "more" link, so the opening line carries nearly all the weight. The separate promotional text field (170 characters) can be edited without a new build — useful for time-sensitive notes, wrong for release history.
  • Play Store (Android): release notes are capped at 500 characters per language, entered per release and editable afterwards. Same truncation dynamic: the first line or two do the work.
  • Auto-updates: most installs happen silently. The people who actually open the update screen and read your notes are disproportionately your most engaged users — reviewers, power users, the ones who file bugs. Small audience, outsized influence.

So the medium is: a two-line hook, a hard cap, an audience of your keenest users, and (on iOS) no easy edits after the fact. Write for that.

What "bug fixes and improvements" actually costs

Teams don't write the empty sentence because they're lazy — they write it because of process: weekly release trains where most versions genuinely contain plumbing, marketing approval bottlenecks, notes frozen days early for review, and localization overhead multiplying every word. Those are real. The costs are real too, just less visible:

  • You forfeit the one channel that reaches upgraders at the moment of upgrade. A user deciding whether your app deserves 80 MB of their attention reads nothing about why.
  • Your most engaged users learn to stop reading. When a release finally does contain the fix they reported, the notes still say "improvements" — so they never find out you fixed their bug, and the one-star review stays up.
  • It reads as indifference at scale. Ratings prompts, review replies, and support macros all point users at "what changed"; if the answer is boilerplate, the whole loop feels automated.

The empty sentence is fine for a version that truly is invisible plumbing — if it's occasional. As a permanent policy it's a standing announcement that nothing you ship is worth describing.

Patterns that work in two lines

  • Lead with the one thing. Pick the single most user-visible change and put it in line one, plainly: "You can now export your workout history as CSV." Everything else goes below the fold.
  • Name the pain when fixing. "Fixed the crash when opening a shared album from a notification" tells your reporters you heard them. "Various stability fixes" tells them nothing. Same rule as any changelog entry — symptoms, not internals.
  • Keep an honest evergreen block, short. If the train shipped nothing visible: "This week: under-the-hood work for something bigger — details soon." Honest, two seconds, doesn't pretend.
  • Be careful with the comedy routine. Jokey release notes were a signature once; they age badly when the same joke ships 40 weeks straight and users with a real bug can't find whether it's fixed. Charm is seasoning, not the meal.
  • Localize the first line at minimum. A 500-character limit per language is also a translation budget. If you can't localize everything, localize the hook.

Release trains, staged rollouts, and when to write

Two mechanics trip teams up. First, on a weekly train the version being submitted was cut days ago — so write the note when the change merges, not at submit time, or the person writing notes is archaeologist rather than author. (The same capture-at-the-moment insight that Changesets applies to monorepos.) Second, staged rollouts and feature flags mean a "released" feature may be off for 90% of users. The store note should cover what's actually on: announce flagged features when the flag opens, not when the binary lands — which usually means the announcement belongs on your changelog page, timed independently of the binary.

The two-layer setup

The store field is a teaser with a hard cap. The durable record lives on a page you control:

  • Store notes: two or three lines, the hook and the top fix. That's all the medium rewards.
  • A full web changelog carries the complete dated history — screenshots, details, the deprecation notices — and is linkable from support replies, review responses, ratings prompts, and the app's own settings screen. Store fields disappear version by version; the page accumulates and compounds as proof you ship.

This also solves the iOS can't-edit problem: the store note can stay short and safe while the web page carries anything you might need to amend.

Where Wakelog fits

Wakelog is the second layer: a hosted changelog page your release pipeline can post to with one curl from CI — same job that builds the binary — or on a schedule with --at so the web announcement lands when the staged rollout opens, not when the build uploads. Tag entries new/fix, link the page from your app's settings screen and review replies, and let users who want detail subscribe by RSS. The store gets its two lines; everyone else gets the whole story.

Start a free changelog   How to write the entries themselves

Related guides

Last updated 2026-07-26 · All guides