Craft

How to Write an App Changelog Your Users Will Actually Read

What Apple and Google require in release notes, why 'Bug fixes and improvements' leaves retention on the table, and a reusable template for writing changelog entries users actually read.

8 min read

How to Write an App Changelog Your Users Will Actually Read

You ship a new version. CI is green, the build is uploaded, and App Store Connect is blinking at you for one last thing: the "What's New in This Version" text. You type "Bug fixes and improvements" because it is 11pm and you have another release tomorrow. The reviewer approves it. Your users scroll past it. A small retention lift you could have earned by naming the thing you actually fixed never shows up in the dashboard.

This guide covers what Apple and Google require in the release-notes field, why "Bug fixes and improvements" is the safe-but-expensive default, and a reusable template you can paste into every release.

TL;DR

  • Release notes are mandatory for every version update on both the App Store and Google Play. Both render them as the "What's New" on your product page.
  • "Bug fixes and improvements" is accepted but leaves retention gains on the table every release.
  • A good entry groups changes by type (Added / Changed / Fixed / Security) and stays short enough to read on a phone.
  • Use the store field as a headline that links to a hosted page with the full history.
  • AppLander gives each app a dedicated changelog page next to its privacy policy, terms, support center, and status page — a stable URL to link from the store "What's New" box.

Table of Contents

What Apple and Google Actually Require

On the App Store, "What's New in This Version" is a required, localizable, editable property for every version update — not for the initial submission, but for every release after that. Apple lets you edit the text without shipping a new build, so you can tweak copy after a version is live.

On Google Play, the equivalent field lives in the release flow under "What's new in this release," localized per store-listing language and shown under "What's New" on the Play product page.

Both stores treat this field as part of your store listing, not a compliance artifact — no rejection for a thin entry, just a soft cost in trust. And both truncate in the compact view, so the first line does the heavy lifting — a phone user sees roughly the first ~150 characters before tapping "more."

Why This Is Harder Than It Looks

The hard part is not typing words into a box. The hard part is deciding which words — every release, under deadline, without drifting into either extreme.

The "Bug fixes and improvements" extreme is optimized for speed. Never wrong, never leaks a feature, takes five seconds. But it tells users nothing: users waiting for a specific fix do not learn it landed, and ASO tools see nothing new.

The "full engineering changelog" extreme dumps every ticket and commit into the store field and reads like CI output.

The productive middle is a categorized, user-facing entry written in the voice of the app. It compounds into a public record of momentum — a retention asset a string of identical "Bug fixes and improvements" lines never will be.

What a Good Changelog Entry Contains

Borrowing from Keep a Changelog — the widely adopted community convention — a good entry groups changes into stable categories and describes each in one short sentence focused on the user outcome. Keep a Changelog leads with a blunt principle: "Changelogs are for humans, not machines." The four categories that travel best to consumer apps:

  • Added — new features, screens, integrations.
  • Changed — behavior that existed before but works differently now.
  • Fixed — bugs from the previous version. Where you cash in retention.
  • Security — vulnerabilities called out in their own category.

Each entry should be a single plain sentence in a category → description → context format. A hypothetical good note: "Fixed the crash that happened when adding a photo larger than 20 MB." A bad one: "Fixed NPE in photo upload pipeline (ref ENG-4471)." Same fact, different audience.

Tone and Length

Match the app's voice. Second person reads better than passive voice, present tense better than past.

Length is driven by the store field. Both stores truncate around the first ~150 characters, so your most important change belongs in the first line. Aim for under ~500 characters total and link to a hosted page for the long version.

Localization matters. If you ship in five languages but only write English release notes, the other four listings silently fall back to the last translated version — a user in Berlin sees a stale changelog from three releases ago.

A Reusable Changelog Template

Steal this. For the store field:

<One-line headline of the biggest change>

New
- <Added item>

Improved
- <Changed item>

Fixed
- <Fixed item>

Full changelog: https://yourapp.example.com/changelog

For the hosted page:

## 2.3.0 — 2026-04-10

### Added
- <One short sentence per item>

### Changed
- <One short sentence per item>

### Fixed
- <One short sentence per item>

Three rules: never publish a version with all categories empty; never mix categories in one bullet; always include version number and release date.

Tools and Approaches Compared

Four patterns for a changelog page that lives longer than the store field.

A GitHub CHANGELOG.md file

Pros.

  • Zero cost if the repo is already on GitHub.
  • Version control is free — every edit is a commit.
  • Keep a Changelog convention is immediately recognizable.

Cons.

  • Consumer users are not visiting a GitHub repo to read what changed.
  • Does not render cleanly from a store listing link.

Best for. Open-source and dev-tool apps whose audience lives on GitHub.

A Notion or marketing-site page

Pros.

  • Fast to set up if your site is a static generator.
  • Full control over layout and cross-linking to feature docs.
  • Easy to share publicly or embed in an in-app "What's new" screen.

Cons.

  • You have to remember to update it every release — drift is the default.
  • Localization is manual and error-prone.

Best for. Teams with the discipline to keep it current.

A dedicated changelog SaaS

Pros.

  • Purpose-built UI with in-app widgets, email digests, and subscriber management.
  • Analytics on which entries users actually open.
  • Polished editing experience designed for marketing rather than engineering.

Cons.

  • Another subscription for a small surface.
  • Rarely integrated with the other compliance assets your app needs.

Best for. Teams where the changelog drives real product-marketing cycles.

An all-in-one compliance-and-craft platform

Pros.

  • Changelog lives alongside privacy, terms, support, and status with one visual identity.
  • One login, one billing, one place for every public page your app needs.
  • Mobile-first by default.

Cons.

  • Overkill if you only need a changelog page.
  • Newer category with less gravity for in-app widgets.

Best for. Indie developers who also need the other compliance pages.

The AppLander Approach

AppLander gives every app a dedicated changelog page at yourapp.applander.io/changelog or on your custom domain, alongside the rest of the compliance stack store listings require.

Standard structure. Each entry has a version, a release date, and a body in the Added / Changed / Fixed / Security groups. The hosted page is the long-form history; the short copy in App Store Connect and Play Console links to it with a stable URL.

Multi-language publishing. Author once and publish in English, German, Italian, French, Arabic, Persian, Swedish, Turkish, and Chinese — so your German listing's "What's New" and the German hosted page tell the same story.

Consistent visual identity. The changelog uses the same layout as your privacy policy, terms, support center, and status page — so any link from the store listing lands on pages that feel like one product.

Stable per-app URLs. The page lives at a permanent URL you can paste into the marketing URL field, the footer of your support center, and the "Full changelog" link inside store release notes.

Honest limitations. AppLander's changelog is a publishing surface, not release automation — no CI pipeline hook, no conventional-commit extraction, no push to the App Store. For git-tag-to-store automation, a dedicated release tool fits better. It is also newer than the SaaS options, with less gravity for in-app widgets and email digests.

Where it wins is the common case: a changelog page that has to look consistent with five other pages, without paying for five subscriptions. Pair it with the mobile app launch compliance checklist and the status page guide.

Step-by-Step

  1. Pull the list of merged PRs or tickets — raw material, not output.
  2. Sort into four buckets: Added, Changed, Fixed, Security. Drop engineering-only changes.
  3. Rewrite each item as one plain sentence on the user outcome. Strip ticket IDs and jargon.
  4. Pick the biggest change as a one-line headline for the store field.
  5. Paste the short version into App Store Connect and Play Console with a link to the hosted page.
  6. Publish the hosted page with version, date, and full categorized body above the previous version.
  7. Translate for every store-listing language you ship.
  8. Ship, then check "What's New" on your product page from a phone in incognito.

Frequently Asked Questions

Is "Bug fixes and improvements" actually against Apple or Google's rules?

No. Neither store rejects the safest, laziest entry. The cost is on you — users who might have re-engaged do not see a reason to.

How long can the "What's New" text be?

Both stores accept more than most users read. The practical limit is the truncation point in the compact view, around the first ~150 characters. Aim for a one-line headline plus a short grouped body, and link to a hosted page for the long version.

Do I need to translate release notes for every store-listing language?

Yes. Store listings fall back to your default language when a localized note is missing, so users reading the German listing end up seeing English — or stale German notes from an older version.

Should I post the changelog inside the app as well?

Probably yes for any app with a meaningful upgrade cadence. An in-app "What's new" screen catches users who never read store release notes. The source of truth should be the same hosted page.

Does the changelog version need to match the binary?

Yes. The hosted version should match what users see in Settings and the store listing. Mismatched numbers are a real source of support-ticket confusion.

Is a security entry safe to publish before the fix rolls out?

No. Publish it only after a meaningful fraction of users are on the patched version. If the vulnerability is serious, phase the rollout and delay the security entry.

Conclusion

A changelog is a small surface with outsized leverage — the cheapest retention lever on the product page. Pick a template, stick to Added / Changed / Fixed / Security, write in the app's voice, translate for every language you ship, and link to a stable hosted page.

If you want that page next to your privacy policy, terms, support center, and status page — one dashboard, multi-language — try AppLander.

Sources

Ship your app faster with AppLander

The all-in-one compliance and landing-page platform for mobile app developers.

Start Free