Asc Whats New Writer

asc What's New Writer

Generate engaging, localized release notes from flexible input. Optionally pair with promotional text updates.

Preconditions

• Metadata pulled locally into canonical files via asc metadata pull --app "APP_ID" --version "1.2.3" --dir "./metadata". OR: user provides keywords manually.
• Auth configured for upload (asc auth login or ASC_* env vars).
• The primary locale is en-US unless the user specifies otherwise.

Before You Start

1. Read references/release_notes_guidelines.md for tone, structure, and examples. 2. Identify the latest version directory under metadata/version/ (highest semver). Use this for all metadata reads. 3. Enumerate existing locales by listing the JSON files in that version directory.

Phase 1: Gather Input

Accept one of three input modes (auto-detect):

Git Log

Parse commits since the last tag:

# Find latest tag
git describe --tags --abbrev=0

# List commits since that tag
git log $(git describe --tags --abbrev=0)..HEAD --oneline --no-merges

Filter out noise: merge commits, dependency bumps, CI changes, formatting-only commits. Extract user-facing changes.

Bullet Points

User provides rough bullets like:

• "improved search"
• "fixed crash on launch"
• "added sleep timer"

Free Text

User describes changes conversationally:

"We made search faster, fixed that annoying crash when you open the app, and added a sleep timer feature"

The skill extracts and structures the changes from the text.

No Input Provided

Prompt the user: "What changed in this release? You can paste git log output, bullet points, or just describe the changes."

Phase 2: Draft Notes (Primary Locale)

Step 1: Classify Changes

Group changes into sections per the guidelines:

• New — new features or capabilities
• Improved — enhancements to existing features
• Fixed — bug fixes users would notice

Omit empty sections. If all changes are fixes, only show "Fixed."

Step 2: Write Benefit-Focused Copy

Follow the tone rules from references/release_notes_guidelines.md:

• Describe user impact, not implementation details
• Use direct address ("you") and action verbs
• Be specific — mention concrete improvements

Step 3: Front-Load the Hook

The first ~170 characters are the only visible part before "more." Lead with the single most impactful change in a complete, compelling sentence.

Step 4: Echo Keywords for Conversion

1. Read keywords from metadata/version/{latest}/{primary-locale}.json

• These canonical files are also what asc metadata keywords ... reads and writes.

2. If the field is empty or missing, skip this step 3. Identify keywords relevant to the changes being described 4. Weave them naturally into the notes — never force or stuff

Step 5: Respect Character Limits

• Keep total length between 500-1500 characters in the primary locale
• This leaves room for localized expansions (some languages expand 30-40%)
• Hard limit: 4,000 characters

Step 6: Optionally Draft Promotional Text

If the user wants it, draft a 170-char promotional text that:

• Summarizes the update's theme in one punchy line
• Can reference seasonal events
• Is updatable without a new submission

Present Draft

Show the draft to the user with character count. Wait for approval before localizing.

Phase 3: Localize

Translate the approved notes to all existing locales.

Translation Rules

• Use formal register and formal "you" forms (Russian: вы, German: Sie, French: vous, Spanish: usted, Dutch: u, Italian: Lei)
• Adapt tone to local market — playful English may need adjustment for formal markets (ja, de-DE)
• Do NOT literally translate idioms — adapt them to local equivalents
• A playful tone in English may need to be more respectful or formal in other cultures

Locale-Specific Keyword Echo

For each locale: 1. Read keywords from metadata/version/{latest}/{locale}.json 2. Echo locale-specific keywords naturally in the translated notes 3. If keywords field is empty, skip echo for that locale

Validate

• All translations must be ≤ 4,000 characters
• Promotional text must be ≤ 170 characters per locale
• If a translation exceeds the limit, shorten it — never truncate mid-sentence

Phase 4: Review & Upload

Step 1: Present Summary

Show a table of all locales with their notes and character counts:

| Locale | What's New (first 80 chars...) | Chars | Promo Text | Chars |
|--------|-------------------------------|-------|------------|-------|
| en-US  | Search just got faster — ...   | 847   | New sleep… | 142   |
| ar-SA  | البحث أصبح أسرع — ...           | 923   | نوم جديد…  | 138   |
| ...    | ...                           | ...   | ...        | ...   |

Step 2: Wait for Approval

Do not upload without user confirmation.

Step 3: Upload

Upload via asc (verify exact syntax with asc --help):

# Individual locale direct update
asc apps info edit --app "APP_ID" --version-id "VERSION_ID" --locale "en-US" --whats-new "Your release notes here"

# Bulk canonical-metadata push after writing ./metadata/version/<version>/<locale>.json
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"

If promotional text was drafted, either include --promotional-text "..." in the direct update command or write promotionalText into the canonical JSON before asc metadata push.

Step 4: Handle Failures

On partial upload failure:

• Report which locales succeeded and which failed
• Offer to retry failed locales

Metadata File Paths

• Keywords: metadata/version/{latest-version}/{locale}.json → keywords field
• Current What's New: metadata/version/{latest-version}/{locale}.json → whatsNew field
• Latest version: highest semver directory under metadata/version/
• The canonical ./metadata tree is what asc metadata pull, asc metadata push, and asc metadata keywords ... operate on.
• Follows the same metadata resolution conventions as asc-aso-audit

Notes

• What's New is not indexed for App Store search — write for humans, not algorithms.
• Promotional text is the only metadata field updatable without a new submission.
• The 170-char visible window is the most important part of your release notes.
• Each app update triggers algorithm re-evaluation — the act of updating matters, even if the text doesn't affect ranking.
• Ideal update cadence: every 2-4 weeks.
• For full metadata translation (all fields), use asc-localize-metadata instead.
• For keyword research and optimization, use asc-aso-audit first.
• If the local keyword field is stale before drafting, refresh it with asc metadata pull or inspect planned keyword changes with asc metadata keywords diff.

Release Notes Guidelines

Rules and examples for writing engaging App Store release notes (What's New).

Structure

Three optional sections. Only include sections with content — omit empty ones.

• New — new features or capabilities
• Improved — enhancements to existing features
• Fixed — bug fixes users would notice

The 170-Character Rule

The first ~170 characters of What's New are visible on the app page without tapping "more." This is the hook.

• Lead with the single most impactful change
• Write a complete, compelling sentence — not a truncated list
• Assume most users will never tap "more"

Example hook (168 chars): "Search just got faster — find what you need in seconds. Plus: smarter notifications and smoother transitions throughout the app."

Tone

• Benefit-focused, not feature-focused. "Find your favorites in seconds" not "Optimized search indexing algorithm."
• Engaging but not fluffy — every word earns its place
• Direct address ("you") to create connection
• Action verbs over passive descriptions ("Track your progress" not "Progress tracking added")
• Specific over vague — mention concrete improvements, not abstract promises

Anti-Patterns

Good vs. Bad Examples

Bad: "Bug fixes and performance improvements."

Good: "Search just got faster — find what you need in seconds. Plus: improved notification accuracy and smoother transitions throughout the app."

---

Bad: "Version 2.1.0 — We've been working hard on improvements!"

Good: "New sleep timer options let you drift off to soothing audio. Choose 15, 30, 45, or 60 minutes — perfect for winding down before bed."

---

Bad: "Fixed bugs. Updated UI. Various improvements across the app."

Good: "Real-time highlighting is now perfectly synced, even at 2x speed. Dark mode colors are easier on the eyes, and the app launches 40% faster."

---

Bad: "We fixed a crash that some users reported. Also updated some things in the background."

Good: "No more crashes when switching between tabs — thanks for reporting this! Background sync is now 3x faster, so your data stays up to date."

Keyword Echo Strategy

What's New is not indexed for App Store search. Keywords here serve conversion only — users who see familiar search terms in the release notes feel confident they found the right app.

How to echo: 1. Read the locale's keywords field from local metadata 2. Identify keywords relevant to the changes being described 3. Weave them naturally into sentences — do NOT force irrelevant keywords 4. If the keywords field is empty or missing, skip this step

Example: If keywords include workout,tracker,calories: "Improved workout tracking accuracy and real-time calorie counter updates" naturally echoes three keywords.

Do NOT: Insert keywords that have nothing to do with the update. "Bug fix for login screen" should not mention "workout" or "calories."

Promotional Text Pairing

When drafting What's New, optionally draft a matching Promotional Text (170 chars max):

• Summarize the update's theme in one punchy line
• Can reference seasonal events (Ramadan, Eid, back-to-school, New Year)
• Updatable without app submission — the only "living" metadata field
• Not indexed for search — write purely for conversion
• Refresh monthly or with each major update for re-engagement

Example: "New sleep timer + faster search. Your evening routine just got better."

Localization Notes

• Formal register across all languages — use formal "you" forms (Russian: вы, German: Sie, French: vous, Spanish: usted)
• Cultural adaptation over literal translation — idioms and playful phrases need local equivalents, not word-for-word translation
• Load locale-specific keywords and echo them in the translated notes (each locale has different keywords)
• Account for text expansion — some languages expand 30-40% vs. English. Aim for 500-1500 chars in English to leave room.
• Validate all translations fit within 4000-char limit
• If translation exceeds the limit, shorten — never truncate mid-sentence

Character Limits