App Store Release Notes Writer

Write human-focused release notes, optionally localized to every existing metadata locale.

Use appstore-metadata-sync for general listing metadata edits, appstore-metadata-localizer for full listing translation, and appstore-subscription-localizer for subscription/IAP display-name localization.

Preconditions

• Canonical metadata from asc metadata pull --app "APP_ID" --version "1.2.3" --dir "./metadata" or user-provided keywords.
• Auth configured for upload.
• Primary locale is en-US unless specified.
• Read references/release_notes_guidelines.md.
• Use highest semver under metadata/version/; locales are the JSON files there.

Workflow

1. Gather input:

• Git log: git describe --tags --abbrev=0 then git log <tag>..HEAD --oneline --no-merges; remove merges/deps/CI/format noise.
• User bullets or free text.
• If absent, ask what changed.

1. Classify user-visible changes into New, Improved, Fixed; omit empty sections.
2. Draft primary locale notes:

• lead with the clearest user-facing hook in the first ~170 chars;
• describe user impact, not implementation;
• use concrete action verbs;
• naturally echo relevant local keywords from metadata/version/<version>/<locale>.json when present;
• target 500-1500 chars, hard limit 4000.

1. If requested, draft promotionalText <= 170 chars.
2. Show draft with character count and wait for approval before localizing.
3. Localize approved notes:

• formal/professional register and formal "you" where applicable;
• adapt idioms and tone to local market;
• echo locale-specific keywords naturally;
• validate What's New <= 4000 and promo <= 170; shorten, never truncate mid-sentence.

1. Present a locale table with first 80 chars, counts, promo text/counts; wait for upload approval.
2. Upload:

   asc apps info edit --app "APP_ID" --version-id "VERSION_ID" --locale "en-US" --whats-new "..."
   asc metadata push --app "APP_ID" --version "1.2.3" --dir "./metadata" --dry-run
   asc metadata push --app "APP_ID" --version "1.2.3" --dir "./metadata"

Include promo via --promotional-text or write promotionalText into canonical JSON before push.

Paths

• Keywords/current notes: metadata/version/{latest-version}/{locale}.json
• Fields: keywords, whatsNew, optional promotionalText
• Canonical tree is shared with asc metadata pull/push/keywords.

Rules

• What's New is not App Store search-indexed; write for conversion and clarity.
• Promotional text can update without a new submission.
• The visible 170-char preview matters most.
• On partial upload failure, report successes/failures and retry failed locales only.
• Use appstore-metadata-localizer for full listing translation and appstore-aso-auditor for keyword research.