release-note-generation

リリースノート生成スキル

マージ済み PR を収集し、ローカル CLI エージェントで各 PR を要約してラベルごとにグループ化し、ユーザー向けの要約を作成することで、プロフェッショナルな PowerToys リリースノートを生成します。安定版リリースとプレビューリリースでは、PR のメタデータ、クレジット表記、グループ化、書式設定に同じルールを適用します。

出力ディレクトリ

生成された成果物はすべて、リポジトリのルートにある Generated Files/ReleaseNotes/（gitignore 対象）に配置されます。

Generated Files/ReleaseNotes/
├── milestone_prs.json           # Raw PR data from GitHub
├── sorted_prs.csv               # Sorted PR list with Copilot summaries
├── prs_with_milestone.csv       # Milestone assignment tracking
├── grouped_csv/                 # PRs grouped by label (one CSV per label)
├── grouped_md/                  # Generated markdown summaries per label
└── v{VERSION}-release-notes.md  # Final consolidated release notes

プレビューリリースの実行では、分離されたサブディレクトリを使用します。

Generated Files/ReleaseNotes/preview-<buildId>/
├── release-context.json
├── delta-commits.json
├── delta-prs.json
├── removed-prs.json
├── unattributed-commits.json
├── MemberList.md
├── milestone_prs.json
├── sorted_prs.csv
├── release-notes.md
├── hashes.md
├── release-manifest.json        # Local audit artifact; never uploaded
├── assets-manifest.json         # Local asset inventory; never uploaded
└── final-review.md

このスキルを使用する場面

• マイルストーンのリリースノートを生成する
• リリースに含まれるマージ済み PR を要約する
• リリースノートの文案作成用に、PR ごとのレビュー要約をローカルで生成する
• マイルストーンが設定されていない PR にマイルストーンを割り当てる
• 2 つのコミットまたはタグの間にある PR を収集する
• 新しいバージョン向けに README.md を更新する
• GitHub リリースのアセットを準備する（インストーラー／シンボルをダウンロードし、ハッシュを計算する）
• ADO ビルド URL またはビルド ID からプレビューリリースのドラフトを一式準備する
• main と stable ブランチの切り替え前後でプレビューの内容を比較する

前提条件

• GitHub CLI（gh）がインストールされ、認証済みであること — 収集スクリプトは gh pr view と gh api graphql を使用して、PR のメタデータと共同作成者情報を取得します。gh auth status を実行して確認してください。ログインしていない場合は、先に gh auth login を実行してください。詳細は 手順 1.0.0 を参照してください。
• MCP サーバー：github-mcp-server がインストールされていること（ローカルエージェントによるレビュー手順で PR の差分／ファイルを取得するために使用します）
• プレビューリリースおよび prepare-release-assets.ps1 では、Microsoft テナントに対して認証済みの Azure CLI（az login）と azure-devops 拡張機能、および ADO プロジェクト microsoft/Dart へのアクセスが必要です

必須変数

安定版リリースでは、開始前にユーザーに {{ReleaseVersion}} を確認してください。 プレビューリリースでは、バージョンを尋ねないでください。候補となる ADO ビルドからバージョンを特定します。

変数	説明	例
{{ReleaseVersion}}	対象のリリースバージョン	0.98

プレビューモードでは、代わりに ADO ビルド URL または数値のビルド ID が必要です。ユーザーに尋ねることなく、バージョン、ソースコミット、ブランチ、前回のリリースを特定します。

シナリオの選択

シナリオの一覧を読み、選択したシナリオだけに従ってください。

• マイルストーンまたはバージョンに基づくリリースノートには、安定版リリースを使用します。
• ADO ビルドからドラフトまでを自動で行うワークフローには、プレビューリリースを使用します。

ワークフローの概要

┌────────────────────────────────┐
│ 1.0 Verify gh auth + MemberList │
└────────────────────────────────┘
              ↓
┌────────────────────────────────┐
│ 1.1 Collect PRs (stable range) │
└────────────────────────────────┘
              ↓
┌────────────────────────────────┐
│ 1.2 Assign Milestones           │
└────────────────────────────────┘
              ↓
┌────────────────────────────────┐
│ 2.1–2.4 Label PRs (auto+human)  │
└────────────────────────────────┘
              ↓
┌────────────────────────────────┐
│ 3.1 Local-agent PR summaries    │
│ (writes CopilotSummary)         │
└────────────────────────────────┘
              ↓
┌────────────────────────────────┐
│ 3.2 (Optional) Refresh PR data  │
└────────────────────────────────┘
              ↓
┌────────────────────────────────┐
│ 3.3 Group by label              │
│ (grouped_csv)                   │
└────────────────────────────────┘
              ↓
┌────────────────────────────────┐
│ 4.1 Summarize (grouped_md)      │
└────────────────────────────────┘
              ↓
┌────────────────────────────────┐
│ 4.2 Final notes (v{VERSION}.md) │
└────────────────────────────────┘

手順	アクション	詳細
1.0	前提条件を確認	gh auth status が成功することを確認し、MemberList.md を生成します
1.1	PR を収集	stable ブランチの前回のリリースタグから → sorted_prs.csv
1.2	マイルストーンを割り当て	すべての PR に正しいマイルストーンが設定されていることを確認します
2.1–2.4	PR にラベルを付ける	ラベルを自動提案し、信頼度が低いものには人手でラベルを付けます
3.1–3.3	レビューとグループ化	ローカルエージェントが各 PR の差分を CopilotSummary に要約 →（任意で更新）→ ラベルごとにグループ化します
4.1–4.2	要約と最終調整	グループごとの要約を生成し、統合します

詳細なワークフローのドキュメント

すべての手順を一度に読まず、実行する手順だけを読んでください。

• 手順 1：収集とマイルストーン
• 手順 2：PR にラベルを付ける
• 手順 3：レビューとグループ化
• 手順 4：要約

利用可能なスクリプト

スクリプト	用途
dump-prs-since-commit.ps1	コミット／タグ間の PR を取得します
group-prs-by-label.ps1	PR を CSV にグループ化します
collect-or-apply-milestones.ps1	マイルストーンを割り当てます
diff_prs.ps1	PR の差分を増分で取得します
prepare-release-assets.ps1	ADO ビルドからインストーラーとシンボルをダウンロードし、SHA256 を計算して、GitHub リリースページ用の「インストーラーのハッシュ」Markdown テーブルを出力します
get-release-build-metadata.ps1	候補ビルドの識別情報、バージョン、チャネル、意図、ソースコミットを解決して検証します
get-previous-published-release.ps1	候補のキュー登録時刻より前に公開された、最新の安定版またはプレビュー版リリースを選択します
get-preview-release-delta.ps1	正確なリリースコミット間で、意味上の追加／削除された PR を計算します
collect-pr-metadata.ps1	明示的に指定された PR 番号の GitHub メタデータを正規化します
new-preview-release-manifest.ps1	監査可能なビルド、ベースライン、意味差分のリリースマニフェストを作成します
upsert-draft-preview-release.ps1	公開操作を行わずに、ドラフトのプレリリースを作成または更新します
verify-draft-preview-release.ps1	ドラフトフラグ、対象コミット、管理対象の本文、アップロード済みアセットを検証します

参考資料

• 出力サンプル - まとめの書式例
• 詳細な手順 - 旧版の完全なドキュメント

規約

• ターミナルの使用：デフォルトでは無効です。ユーザーが明示的に要求した場合にのみスクリプトを実行します
• プレビューの自動化：プレビューリリースの準備を明示的に依頼された場合、または Prepare Preview Release エージェントが実行された場合は、正規のプレビュースクリプトを実行する権限が付与されます
• プレビューマニフェスト：ローカル監査パッケージには release-manifest.json と assets-manifest.json を含めます。いずれのファイルも GitHub リリースアセットとしてアップロードしないでください
• プレビューノートのレイアウト：Installer Hashes セクションは、タイトルと短い公開向け紹介文の直後、Highlights とすべての変更セクションの前に配置します
• 一括生成：すべての grouped_md ファイルを一度に生成し、その後、人が確認します
• PR の順序：すべての出力で sorted_prs.csv の順序を維持します
• ラベルによる絞り込み：Product-*、Area-*、GitHub*、*Plugin、Issue-* を保持します

トラブルシューティング

問題	解決策
gh コマンドが見つからない	GitHub CLI をインストールし、PATH に追加します
PR が返されない	マイルストーンのタイトルが完全に一致していることを確認します
多数の PR で CopilotSummary が空	ステップ 3.1（ローカルエージェントによる要約）を実行します。CLI／コーディングエージェントから mcp_github_request_copilot_review を使用しないでください。GitHub API はボットが開始したレビューリクエストを拒否するため、この列は空のままになります。
ラベルのない PR が多数ある	グループ化の前にラベル付けのステップに戻ります
prepare-release-assets.ps1 が「Failed to acquire ADO access token」で失敗する	az login を実行し、microsoft/Dart ADO プロジェクトへのアクセス権があることを確認します
候補に release-metadata.json がない	メタデータ解決ツールはパイプラインログへのフォールバックを使用します。値が曖昧または競合している場合、処理は停止します
ブランチ切り替え後、最初のプレビューで予期しない変更がある	removed-prs.json と unattributed-commits.json を確認してください。プレビュー差分の解決を参照してください