asc-whats-new-writer

asc 新機能紹介文の作成

柔軟な入力から、魅力的でローカライズされたリリースノートを生成します。必要に応じて、プロモーションテキストの更新も併せて作成できます。

前提条件

• asc metadata pull --app "APP_ID" --version "1.2.3" --dir "./metadata" を使用して、メタデータをローカルの標準ファイルに取り込み済みであること。または、ユーザーがキーワードを手動で指定していること。
• アップロード用の認証が設定済みであること（asc auth login または ASC_* 環境変数）。
• ユーザーが別途指定しない限り、プライマリロケールは en-US です。

始める前に

1. トーン、構成、例について、references/release_notes_guidelines.md を読みます。
2. metadata/version/ の下にある最新のバージョンディレクトリ（最も大きい semver）を特定します。すべてのメタデータの読み取りにこのディレクトリを使用します。
3. そのバージョンディレクトリ内の JSON ファイルを一覧表示して、既存のロケールを列挙します。

フェーズ 1：入力の収集

次の 3 つの入力モードのいずれかを受け付けます（自動検出）。

Git ログ

最後のタグ以降のコミットを解析します。

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

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

ノイズ（マージコミット、依存関係の更新、CI の変更、フォーマットのみの変更）を除外します。ユーザー向けの変更を抽出します。

箇条書き

ユーザーは、次のような大まかな箇条書きを提示します。

• 「検索を改善」
• 「起動時のクラッシュを修正」
• 「スリープタイマーを追加」

自由形式のテキスト

ユーザーが変更内容を会話形式で説明します。

「検索を高速化し、アプリを開いたときに起きる厄介なクラッシュを修正して、スリープタイマー機能を追加しました」

このスキルは、テキストから変更内容を抽出し、整理します。

入力がない場合

ユーザーに次のように尋ねます。「このリリースで何が変わりましたか？ Git ログの出力や箇条書きを貼り付けるか、変更内容をそのまま説明してください。」

フェーズ 2：リリースノートの下書き（プライマリロケール）

ステップ 1：変更を分類する

ガイドラインに従って、変更をセクションごとに分類します。

• 新機能 — 新しい機能や性能
• 改善 — 既存機能の強化
• 修正 — ユーザーが気づく不具合の修正

空のセクションは省略します。変更がすべて修正の場合は、「修正」のみを表示します。

ステップ 2：メリットを重視した文章を書く

references/release_notes_guidelines.md のトーンに関するルールに従います。

• 実装の詳細ではなく、ユーザーへの影響を説明します
• ユーザーに直接語りかけ、行動を表す動詞を使います
• 具体的に書き、明確な改善点に言及します

ステップ 3：冒頭に要点を置く

最初の約 170 文字だけが、「続きを読む」の前に表示されます。最も影響の大きい変更を、魅力的で完結した一文で冒頭に記載します。

ステップ 4：キーワードを自然に盛り込んでコンバージョンにつなげる

1. metadata/version/{latest}/{primary-locale}.json から keywords を読み取ります
   • これらの標準ファイルは、asc metadata keywords ... の読み取りと書き込みにも使用されます。
2. フィールドが空または存在しない場合は、このステップを省略します
3. 説明する変更に関連するキーワードを特定します
4. 無理に詰め込まず、自然にリリースノートに盛り込みます

ステップ 5：文字数制限を守る

• プライマリロケールでの総文字数を 500～1500 文字にします
• これにより、ローカライズ時の文字数増加（言語によって 30～40％増加）に対応できます
• 上限は 4,000 文字です

ステップ 6：必要に応じてプロモーションテキストの下書きを作成する

ユーザーが希望する場合は、次の条件を満たす 170 文字のプロモーションテキストを作成します。

• アップデートのテーマを、印象的な一文で要約する
• 季節のイベントに言及してもよい
• 新しい提出を行わずに更新できる

下書きを提示する

文字数とともに下書きをユーザーに提示します。ローカライズを始める前に、承認を待ちます。

フェーズ 3：ローカライズ

承認されたリリースノートを、既存のすべてのロケールに翻訳します。

翻訳ルール

• 敬体と丁寧な二人称形式を使用します（ロシア語：вы、ドイツ語：Sie、フランス語：vous、スペイン語：usted、オランダ語：u、イタリア語：Lei）
• 現地市場に合わせてトーンを調整します。英語で遊び心のある表現は、格式を重んじる市場（ja、de-DE）では調整が必要な場合があります
• 慣用表現を逐語訳せず、現地の相当表現に置き換えます
• 英語で遊び心のあるトーンは、ほかの文化圏ではより敬意を払った、またはフォーマルな表現にする必要がある場合があります

ロケール固有のキーワードの反映

ロケールごとに、次の手順を実行します。

1. metadata/version/{latest}/{locale}.json から keywords を読み取ります
2. ロケール固有のキーワードを、翻訳したリリースノートに自然に盛り込みます
3. keywords フィールドが空の場合、そのロケールではキーワードの反映を省略します

検証

• すべての翻訳は 4,000 文字以下である必要があります
• プロモーションテキストはロケールごとに 170 文字以下である必要があります
• 翻訳が制限を超える場合は、短縮してください — 文の途中で切り捨てないでください

フェーズ 4: レビューとアップロード

ステップ 1: サマリーを提示する

すべてのロケールのメモと文字数を表で示します:

| 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   |
| ...    | ...                           | ...   | ...        | ...   |

ステップ 2: 承認を待つ

ユーザーの確認なしにアップロードしないでください。

ステップ 3: アップロード

asc でアップロードします（正確な構文は 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"

プロモーションテキストを作成した場合は、直接更新コマンドに --promotional-text "..." を含めるか、asc metadata push の前に正規の JSON に promotionalText を書き込んでください。

ステップ 4: 失敗に対処する

部分的なアップロード失敗時:

• どのロケールが成功し、どのロケールが失敗したかを報告する
• 失敗したロケールを再試行することを提案する

メタデータのファイルパス

• キーワード: metadata/version/{latest-version}/{locale}.json → keywords フィールド
• 現在の What's New: metadata/version/{latest-version}/{locale}.json → whatsNew フィールド
• 最新バージョン: metadata/version/ 配下の最も高い semver ディレクトリ
• 正規の ./metadata ツリーは、asc metadata pull、asc metadata push、および asc metadata keywords ... が操作する対象です。
• asc-aso-audit と同じメタデータ解決の規約に従います

注意事項

• What's New は App Store 検索でインデックスされません — アルゴリズムではなく人間に向けて書いてください。
• プロモーションテキストは、新しい申請なしで更新できる唯一のメタデータフィールドです。
• 170 文字の表示ウィンドウは、リリースノートの中で最も重要な部分です。
• 各アプリの更新はアルゴリズムの再評価を引き起こします — テキストがランキングに影響しないとしても、更新するという行為自体が重要です。
• 理想的な更新頻度: 2〜4 週間ごと。
• 完全なメタデータ翻訳（すべてのフィールド）には、代わりに asc-localize-metadata を使用してください。
• キーワードの調査と最適化には、まず asc-aso-audit を使用してください。
• 作成前にローカルのキーワードフィールドが古い場合は、asc metadata pull で更新するか、asc metadata keywords diff で予定されているキーワードの変更を確認してください。