App Store release notes: how to write What's New, with examples
App Store release notes go in the What's New in this Version field: up to 4,000 characters per language, required on every update and absent from an app's first version. The text locks with the version, so after release the only copy you can change without a new version is the 170-character promotional text.
Apple shows What's New on your product page and alongside the update itself. App Review reads it too: guideline 2.3.12 says significant changes must be described, while simple bug fixes, security updates and performance work can use a generic line.
Write for someone deciding whether to open your app again. Lead with the change they'll notice, in plain words, then list the rest by importance, which is also Apple's own advice.
By Redjan Hysa, founder of MetaRun · Facts checked October 12, 2026
- characters of What's New per language
- 4,000
- characters of promotional text per language
- 170
- What's New doesn't exist on a first version
- Updates only
- when promotional text can change, with no new submission
- Any time
- for a listing change to show in every storefront
- Up to 24 hours
Reference tables
| Field | Limit | Where it shows | Change after release | Matched in App Store search |
|---|---|---|---|---|
| What's New in this Version | 4,000 characters | Product page and next to the update | No, needs a new version | Not on Apple's list |
| Promotional Text | 170 characters | Above the description, iOS 11 and later | Yes, any time | No (Apple says so) |
| Description | 4,000 characters | Product page | No, needs a new version | Not on Apple's list |
Apple lists the app name, subtitle, keywords and primary category as the text it matches in search. All three fields above are set per language.
| Update | Weak | Better |
|---|---|---|
| Bug fix | Bug fixes and improvements. | Fixed a crash when opening a shared list from a link. Reminders now arrive on time after you change time zones. |
| New feature | New features! | New: home screen widgets. Add today's habits to your home screen and tick them off without opening Loopday. Touch and hold the home screen, tap Edit, then Add Widget. |
| Redesign | We redesigned the app. Hope you like it! | Loopday has a new look. Your habits and history haven't moved, and Stats now has its own tab. Prefer the old list? Turn on Compact List in Settings. |
| Subscription change | Updated subscriptions. | Loopday Pro now includes cloud backup. If you already subscribe, your plan stays the same and backup turns on by itself. |
| Performance | Performance improvements. | Opens faster on older iPhones, and syncing a long history no longer drains the battery. |
| Maintenance only | Version 2.4.1 | Small fixes and support for the latest iOS. Nothing changes in how you use Loopday. |
Loopday is a made-up habit tracker. The maintenance line is generic on purpose: guideline 2.3.12 allows that when the update is only fixes, security or performance work.
| Problem | Example | Guideline |
|---|---|---|
| Naming another mobile platform | "Now on Android too!" | 2.3.10 |
| Placeholder or temporary text | "TBD", "Lorem ipsum", "Notes go here" | 2.1 |
| A generic note for a significant change | "Bug fixes" on the update that adds a paid tier | 2.3.12 |
| Promising what the build doesn't do | "Dark mode is here" when it ships switched off | 2.3.1 |
How to edit What's New and promotional text in App Store Connect
You need the Account Holder, Admin, App Manager or Marketing role. The example is version 2.4 of an app that's already live.
- 01
Create or open the version
In Apps, select the app and click version 2.4 in the sidebar. If it doesn't exist yet, click the add button (+) next to the platform and enter 2.4; Apple carries the current version's metadata over.
- 02
Write What's New in this Version
With the primary language selected, type the notes into What's New in this Version, up to 4,000 characters, and click Save.
- 03
Fill it for every language
Pick each language from the menu at the top right and write its What's New. Apple requires the field on updates, so a language left empty holds up the submission.
- 04
Set promotional text if you want it
Promotional Text is on the same page. On the live version you can edit it at any time and click Save, with no submission.
- 05
Submit the version
Add the build and submit for review. The notes go public when the version is released.
What's New in this Version: the rules that trip people up
There's no What's New field on a first version; App Store Connect shows it only once the app has shipped. On every later version it's required, and each language carries its own text.
Editing follows the version's status. Prepare for Submission, Ready for Review and the rejected statuses are editable. While a version is Waiting for Review, Apple allows only some edits, and In Review allows none. After approval the field is fixed, with one way out: a version still in Pending Developer Release can be removed from review, which sets it to Developer Rejected, so you can edit and resubmit. Review starts over when you do.
Promotional text: the field you can change any time
Promotional text sits above the description for people on iOS 11 or later, and you can change it without submitting a new version. It's 170 characters per language. Apple suggests it for current news such as limited-time sales or upcoming features, which makes it the right place for anything you'd want to say after release.
Apple says promotional text doesn't affect search ranking, so don't spend it on keywords. Custom product pages carry their own promotional text. The description, by contrast, runs to 4,000 characters and only changes with a new version.
How to write release notes people read
Apple's guidance: list new features, content or functionality in order of importance, tell people when a fix came from their feedback, and give them a reason to try the update. Start with the change a user will notice, name the screen or button, and say what it does for them. Long notes are cut off behind a more link, so the opening line has to work alone.
"Bug fixes and performance improvements" is fine when that's all the update is. It wastes the space on an update that adds a feature, and it's a rejection risk on one that changes what people pay for.
Leave out specific prices. Apple advises against them in the description because prices differ by storefront, and the same logic applies here: say what changed in the plan and let the purchase sheet show the price.
What's New and the notes for App Review are separate fields
Guideline 2.3.1 asks you to describe new features and product changes with specificity in the Notes field of App Review Information, and says generic descriptions there will be rejected. What's New is for customers. The review notes are for the reviewer and can say where to find the feature and which test account to use. A significant update needs both.
Localizing release notes
Every language on the version needs its own What's New. Translate the meaning, keep the order, and use the same feature names as the localized app: a note that points to a button should use the button's translated label. MetaRun's listing coverage check names every language still missing What's New before you submit.
Common problems and how to fix them
What's New field missing on the first version
Why: Apple has no What's New on an app's first version. The field appears from the second version on.
Fix: Nothing to fill. Put launch copy in the description and promotional text; What's New appears when you create your next version.
Can't edit What's New after approval
Why: The field locks once the version goes into review and stays locked after approval.
Fix: If the version is Pending Developer Release, remove it from review (it becomes Developer Rejected), edit, and resubmit; review starts over. If it's already live, update promotional text now and correct the notes in your next version.
Release notes not showing in a locale
Why: The viewer gets a different localization from the one you edited, because Apple picks it from the storefront's supported languages and the device language. Or the version isn't live yet, or the change is still propagating.
Fix: Check which languages that storefront supports in Apple's localization reference, make sure each has What's New on the version, and allow up to 24 hours after release.
Rejected over What's New: guideline 2.3.12 or 2.3.10
Why: The notes skip a significant change, name another platform such as Android, or still contain placeholder text.
Fix: Rewrite the notes and reply to App Review in App Store Connect. If the status is Metadata Rejected, you don't need a new build.
Do it from Claude Code, Codex, Cursor or Xcode with MetaRun
Release notes are the last thing anyone writes. By then the version is ready, the build is processed, and twelve languages still say last month's text. Copying translations into App Store Connect one locale at a time takes longer than writing them.
Through MetaRun, your agent writes and translates, and MetaRun does the parts that must be exact: it reads the live version, checks What's New against Apple's 4,000-character limit, stages one change per language, and reports which languages are still missing it.
Before you start
- An update, not a first release: What's New only exists after the app has shipped once.
- The version still editable (being prepared, ready for review, or rejected).
- Something to work from: a changelog, the commit log, or your own notes.
How the agent runs it
- 01
Gather what changed
Your agent works from what it can see: your changelog, merged pull requests, the commit log since the last tag, or what you tell it.
- 02
Read the version in every language
MetaRun returns the version's localizations so the agent knows which languages exist and what they say now.
- 03
Stage one change per language
Each language gets its own preview with the old and new text. Anything over 4,000 characters is refused at preview, not by Apple after submission.
- 04
Confirm coverage
Before calling the job done, your agent reads listing coverage, which lists any language still missing What's New.
An example session
Write What's New for 2.4 from CHANGELOG.md, under 500 characters, friendly but plain. Stage it in English, then translate it into every language on the listing.
- apple_list_version_localizationsVersion 2.4 has 12 languages. What's New is empty in each.
- apple_preview_set_version_localizationPreview: English (U.S.) What's New, 412 of 4,000 characters.
- Your agent asks before running apple_apply_set_version_localization. You read the preview above and approve.
- apple_apply_set_version_localizationApplied for English (U.S.).
- apple_get_listing_coverage11 languages still missing What's New. Your agent continues with those.
Illustrative: your apps, versions and numbers will differ. The tool names and their order are real.
The MetaRun tools involved
| Tool | What it does |
|---|---|
| apple_list_version_localizationsread | Every language on the version with its current What's New, description and keywords. |
| apple_preview_set_version_localizationpreview + apply | Stage What's New (or description, keywords, URLs) for one language. |
| apple_get_listing_coverageread | Which languages are still missing which fields, so the job isn't declared done early. |
| apple_get_listing_editabilityread | Whether the version's text is editable right now. |
| aso_lint_metadataread | Checks copy against App Store rules before it's staged. |
| apple_preview_set_promotional_textpreview + apply | The 170-character line above the description that changes live, without review. |
| aso_schedule_promo_textMetaRun | Schedule promotional text to switch at a set time, for example on launch day. |
Each preview has an apply twin that only runs with the confirm token from a fresh preview, and refuses if App Store Connect changed in between.
What Apple enforces along the way
No What's New on a first version
Apple has no What's New field until the app has shipped once. The API rejects it and App Store Connect hides it, so MetaRun only asks for it on updates.
4,000 characters per language
What's New and the description each allow 4,000 characters. Promotional text allows 170 and is the only one of the three that changes without review.
Text locks once the version is in review
What's New is editable while the version is being prepared or after a rejection. apple_get_listing_editability tells the agent which fields are locked and why, instead of a write failing.
Adding a language creates rows Apple fills in
When a new language is added, Apple creates that language's other localization rows on its own. MetaRun's confirm token is keyed on the language, not Apple's row id, so your approved change doesn't fail as drift.
Set up your agent
Connect once, then ask in plain words. Pick your agent:
Claude Code Anthropic
Run claude mcp add --transport http --scope user metarun https://metarun.dev/api/mcp, then run /mcp in Claude Code and sign in to MetaRun in your browser.
01 · Add the server
Run it in any terminal. --scope user makes MetaRun available in every project; leave it out to limit it to the current one.
claude mcp add --transport http --scope user metarun https://metarun.dev/api/mcp02 · Sign in
In a Claude Code session, run /mcp, choose metarun and authenticate. MetaRun opens in your browser, where you pick read-only or read and change. From a plain shell, claude mcp login metarun does the same.
/mcp03 · Optional: add the skills too
The MetaRun plug-in bundles the same server with six mission skills (release handoff, worldwide pricing, localization, review inbox, ASO audit, store media).
claude plugin marketplace add metarun/metarun-skills
claude plugin install metarun-skills@metarunThen ask Claude Code
- Ask Claude Code: Write What's New for 2.4 from CHANGELOG.md, under 500 characters, friendly but plain. Stage it in English, then translate it into every language on the listing.
- Ask Claude Code: Summarize git log v2.3..HEAD into release notes users would care about. Skip refactors.
- Ask Claude Code: Which languages on 2.4 are still missing What's New?
claude -p runs one request with no interactive session. The browser sign-in can't complete inside -p, so sign in once interactively first, or configure the server with a personal access token in CI. Tools missing from --allowedTools are refused in -p mode.
Read-only check, safe to schedule
claude -p "List every language on the editable version of com.example.app that is missing What's New. Read only." \
--allowedTools "mcp__metarun__apple_list_version_localizations,mcp__metarun__apple_preview_set_version_localization,mcp__metarun__apple_get_listing_coverage,mcp__metarun__apple_get_listing_editability,mcp__metarun__aso_lint_metadata,mcp__metarun__apple_preview_set_promotional_text"Only reads and previews are on that list, so nothing can reach App Store Connect unattended. Run applies in an interactive session where Claude Code can ask you.
Codex OpenAI
Run codex mcp add metarun --url https://metarun.dev/api/mcp; Codex detects MetaRun's sign-in and opens it in your browser.
01 · Add the server
Codex sees that MetaRun offers sign-in and starts it straight away, in your browser. Pick read-only or read and change.
codex mcp add metarun --url https://metarun.dev/api/mcp02 · Sign in again later
If the sign-in expires or you disconnected it in MetaRun's settings. --no-browser prints the link instead, for SSH sessions.
codex mcp login metarun03 · Or edit ~/.codex/config.toml
The Codex CLI, the IDE extension and Codex in the ChatGPT desktop app read the same file, so one entry covers all three.
[mcp_servers.metarun]
url = "https://metarun.dev/api/mcp"Then ask Codex
- Ask Codex: Write What's New for 2.4 from CHANGELOG.md, under 500 characters, friendly but plain. Stage it in English, then translate it into every language on the listing.
- Ask Codex: Summarize git log v2.3..HEAD into release notes users would care about. Skip refactors.
- Ask Codex: Which languages on 2.4 are still missing What's New?
codex exec runs one request without an interactive session and with its approval policy set to never. MetaRun's reads and previews still run, because they're marked read-only; anything that would ask is refused.
Read-only check, safe to schedule
codex exec "List every language on the editable version of com.example.app that is missing What's New. Read only."Applies are refused in codex exec by design. Don't set MetaRun's approval mode to approve just to make them pass; keep App Store changes in an interactive session.
Cursor Anysphere
Add https://metarun.dev/api/mcp to ~/.cursor/mcp.json (or use the install link) and sign in to MetaRun when Cursor opens your browser.
01 · Add to ~/.cursor/mcp.json (or .cursor/mcp.json for one project)
{
"mcpServers": {
"metarun": {
"url": "https://metarun.dev/api/mcp"
}
}
}02 · Or use the install link
Opens Cursor with the server filled in.
https://cursor.com/link/mcp/install?name=metarun&config=eyJ1cmwiOiJodHRwczovL21ldGFydW4uZGV2L2FwaS9tY3AifQ%3D%3D03 · Sign in
When Cursor connects, MetaRun opens in your browser. Pick read-only or read and change, and you're back in the editor with the tools listed under MCP.
Then ask Cursor
- Ask Cursor: Use @CHANGELOG.md to write What's New for 2.4 and stage it for all languages.
- Ask Cursor: The German What's New reads stiff. Rewrite it and show me the preview.
- Ask Cursor: Set promotional text to announce the widget, live now.
The Cursor CLI runs one request without the editor with agent -p. Allow only the read tools the request needs in ~/.cursor/cli-config.json (Mcp(metarun:tool_name) rules), and keep MetaRun's apply tools out of that list.
Read-only check, safe to schedule
agent -p "List every language on the editable version of com.example.app that is missing What's New. Read only." --output-format jsonDon't run it with --force for MetaRun: that approves every tool, applies included.
Xcode Apple
In Xcode 27, add the plug-in from https://github.com/metarun/metarun-skills (Settings, Intelligence, Plug-ins, Add from URL) and click Sign in next to MetaRun.
01 · Add the MetaRun plug-in
In Xcode 27, open Settings, Intelligence, Plug-ins. Choose Add Plug-in, then Add from URL, and paste:
https://github.com/metarun/metarun-skills02 · Or with one click
Opens Xcode's plug-in sheet with the repository filled in.
xcode://agent-plugin-clone?repo=https%3A%2F%2Fgithub.com%2Fmetarun%2Fmetarun-skills03 · Sign in
Install MetaRun from the list, then click Sign in next to it. MetaRun opens in your browser; pick read-only or read and change.
04 · Ask the coding assistant
Claude Agent, Codex and Gemini in Xcode all get MetaRun's tools and its six workflow skills.
Attach build 312 to version 2.4 and tell me what blocks submission.Then ask Xcode
- Ask Xcode: Write What's New for 2.4 based on the commits in this project since the 2.3 tag.
- Ask Xcode: Translate the English What's New into Japanese, Korean and Simplified Chinese and stage them.
- Ask Xcode: Schedule promotional text for launch day at 09:00 UTC.
Claude Anthropic
In Claude, open Customize, Connectors, Add custom connector, paste https://metarun.dev/api/mcp and click Connect to sign in to MetaRun.
01 · Add a custom connector
In Claude, open Customize, then Connectors, and choose Add custom connector. Name it MetaRun and paste the server URL:
https://metarun.dev/api/mcp02 · Connect
Click Connect. Claude opens MetaRun in your browser to sign in; pick read-only or read and change.
03 · Team and Enterprise
An Owner adds the connector once under Organization settings, Connectors. Each member then clicks Connect and signs in to their own MetaRun account.
Then ask Claude
- Ask Claude: Here's what changed in 2.4: offline sync, a new widget, faster launch. Write What's New and stage it in every language.
- Ask Claude: Make the French release notes shorter.
- Ask Claude: Is What's New filled in for every language?
Frequently asked questions
What is the App Store What's New character limit?
4,000 characters per language, the same as the description. Promotional text is limited to 170.
What's the difference between promotional text and the description?
Promotional text is a 170-character line above the description that you can change any time. The description runs to 4,000 characters and changes only with a new version. Neither is on Apple's list of text it matches in search.
Can I change App Store promotional text without a new version?
Yes. Edit it on the live version and click Save; Apple says no new submission is needed. Allow up to 24 hours for it to show everywhere.
Where does promotional text appear on the App Store?
At the top of your product page, above the description, for people on iOS 11 or later. Custom product pages carry their own.
What's a good What's New in this Version example?
Lead with the change people will notice and say where to find it: "New: home screen widgets. Add today's habits to your home screen and tick them off without opening the app." The examples table above covers fixes, redesigns and subscription changes.
Can my release notes just say "bug fixes"?
Yes, if that's all the update contains. Guideline 2.3.12 allows a generic description for simple bug fixes, security updates and performance improvements, but significant changes must be listed.
Do release notes affect App Store search?
Apple names the app name, subtitle, keywords and primary category as the text it matches, plus signals such as downloads and ratings. What's New isn't on that list.
Who writes the translations, your agent or MetaRun?
Your agent does. MetaRun reads the live listing, checks the limits, and stages one change per language for you to approve. Translations through your own agent don't use MetaRun's AI translation budget.
Can your agent update release notes after the app is live?
Not What's New: it locks with the version. Promotional text is the exception and changes the live listing immediately, so that's what to use for a post-launch message.
How many languages can it handle at once?
Every language on your listing. Each one is its own preview, so you can approve some and skip others.
Will it overwrite my description by accident?
Only fields the agent names are touched, and each preview shows the field's old and new text before anything is applied.
Sources
- Apple: Platform version information
- Apple: Creating your product page
- Apple: App Review Guidelines (2.1, 2.3.1, 2.3.10, 2.3.12)
- Apple: Required, localizable, and editable properties
- Apple: App and submission statuses
- Apple: Remove a submission from review
- Apple: Create a new version
- Apple: View and edit app information
- Apple: App Store search
- Apple: App Store localizations
Related guides
Guide
All 50 App Store languages with their codes, which storefronts show and search each one, and how to add, remove or switch the primary language.
Guide
The pre-submission checklist, every review status, export compliance, rejections and expedites.
Guide
The 7-day percentage schedule, the 30-day pause budget, and what to do when a bad build is rolling out.
Guide
The 100-character keyword field: Apple's rules, a worked example, per-language fields, and how to research and measure keywords.
All guides
Releases, TestFlight, pricing, subscriptions, localization, screenshots and more.
With MetaRun: Metadata editor
MetaRun
Do this from your AI agent or MetaRun's dashboard, with a preview before every change. 14-day free trial, no card.