# バッチ設計書 54-Draft-TerminalReleases

## 概要

本ドキュメントは、ビルド成果物（zip/MSIX/プレインストールキット）からGitHubリリースのドラフトを作成するPowerShellスクリプト「Draft-TerminalReleases.ps1」のバッチ設計書である。

### 本バッチの処理概要

本バッチは、指定ディレクトリ配下のTerminalビルド成果物（MSIXバンドル、zipファイル、プレインストールキット）を解析し、バージョン情報・ブランディング（Release/Preview/Canary/Dev）を自動判定した上で、GitHubにタグ付きのドラフトリリースを作成する。各アセットのSHA256ハッシュ値を含むリリースボディを生成し、アセットファイルをリリースにアップロードする。

**業務上の目的・背景**：Windows Terminalのリリースプロセスにおいて、ビルド成果物を手動でGitHubリリースに登録するのは煩雑でエラーが起きやすい。本バッチはこのプロセスを自動化し、バージョン番号の抽出・ブランディングの判定・ハッシュ値の計算・リリースドラフトの作成を一括で行う。

**バッチの実行タイミング**：リリースビルドの成果物が完成した後、リリースエンジニアが手動で実行する。

**主要な処理内容**：
1. 指定ディレクトリからMSIXバンドル・zipファイルを収集
2. 各アセットのタイプ判定（ApplicationBundle/PreinstallKit/GroupPolicy/Zip）
3. MSIXバンドル・プレインストールキットからAppxManifest.xmlを抽出しバージョン・名前を解析
4. zipファイルからwt.exeを抽出しProductVersionを取得
5. ブランディング判定（Release/Preview/Canary/Dev）
6. バージョンモニカーでグループ化しReleaseオブジェクトを構築
7. タグの存在確認とタグ付け方法の対話的選択
8. SHA256ハッシュ値を含むリリースボディの生成
9. PSGitHubモジュールでGitHubドラフトリリースを作成
10. アセットファイルのリリースへのアップロード

**前後の処理との関連**：CIパイプラインでのビルド完了が前提。ドラフトリリース作成後、リリースエンジニアが内容を確認し公開する。

**影響範囲**：GitHubリポジトリのリリースページにドラフトリリースが作成され、ビルドアセットがアップロードされる。

## バッチ種別

リリースエンジニアリング / デプロイ支援

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（リリース時） |
| 実行時刻 | N/A |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | 手動 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| PowerShell 7.0以上 | #Requires -Version 7.0 |
| PSGitHubモジュール | #Requires -Modules PSGitHub |
| ビルド成果物 | 指定ディレクトリにMSIXバンドル・zipファイルが存在すること |
| tarコマンド | ファイルの展開にtarコマンドが利用可能であること |
| Gitリポジトリ | タグの存在確認にgitコマンドが利用可能であること |

### 実行可否判定

指定ディレクトリに.msixbundleまたは.zipファイルが存在する場合に処理を実行する。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| Directory | string[] | No | - | ビルド成果物が格納されたディレクトリパス（複数指定可） |
| Owner | string | No | "microsoft" | GitHubリポジトリのオーナー |
| RepositoryName | string | No | "terminal" | GitHubリポジトリ名 |
| DumpOutput | switch | No | $false | デバッグ用：リリース情報を出力して終了 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| *.msixbundle | MSIXバンドル | アプリケーションバンドル |
| *Preinstall*.zip | ZIP | プレインストールキット |
| GroupPolicy*.zip | ZIP | グループポリシーテンプレート |
| *.zip | ZIP | ポータブル配布用zipアーカイブ |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| GitHub Release (Draft) | GitHub API | ドラフトリリースの作成 |
| GitHub Release Assets | GitHub API | ビルドアセットのアップロード |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| リリース名 | "{ブランド名} v{バージョン}" |
| タグ名 | "v{バージョン}" |
| リリースボディ | SHA256ハッシュ値一覧を含むMarkdown |

## 処理フロー

### 処理シーケンス

```
1. アセット収集
   └─ Get-ChildItemで.msixbundle/.zipファイルを再帰収集
2. アセット解析
   └─ 各アセットのAssetオブジェクトを作成し、Load()でタイプ・バージョン・ブランディングを判定
3. アセットタイプ判定
   ├─ MSIXバンドル: AppxManifest.xmlからバージョンと名前を取得
   ├─ プレインストールキット: 内部のMSIXバンドルを展開して解析
   ├─ zipファイル: wt.exeのProductVersionとファイル名から情報取得
   └─ GroupPolicy: ファイル名から情報取得
4. リリースグループ化
   └─ VersionMonikerでグループ化しReleaseオブジェクトを構築
5. タグ設定の対話的確認
   └─ 既存タグ確認 → タグなしの場合はブランチまたはコミットSHA指定
6. リリースボディ生成
   └─ SHA256ハッシュ値一覧を含むMarkdown文字列を生成
7. ドラフトリリース作成
   └─ New-GitHubRelease でドラフトリリースを作成
8. アセットアップロード
   └─ New-GitHubReleaseAsset で各アセットをアップロード
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[ディレクトリからアセット収集]
    B --> C[各アセットのタイプ・バージョン解析]
    C --> D[ブランディング判定]
    D --> E[VersionMonikerでグループ化]
    E --> F{DumpOutput?}
    F -->|Yes| G[リリース情報を出力して終了]
    F -->|No| H[タグ設定の対話的確認]
    H --> I[リリースボディ生成 - SHA256ハッシュ]
    I --> J[アセットを理想的ファイル名でコピー]
    J --> K[New-GitHubRelease でドラフト作成]
    K --> L[New-GitHubReleaseAsset でアップロード]
    L --> M[バッチ終了]
```

## データベース操作仕様

### 操作別データベース影響一覧

本バッチはデータベース操作を行わない。GitHub APIを通じたリリース操作を行う。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| N/A | ThrowError | プレインストールキットに_License1.xmlが含まれない | ファイルの構成を確認 |
| N/A | ErrorActionStop | $ErrorActionPreference = 'Stop' による即時停止 | エラーメッセージに従い修正 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

### 障害時対応

GitHubにドラフトリリースが部分的に作成された場合は、GitHub UI上で手動削除し再実行する。

## トランザクション仕様

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | リリース単位 |
| コミットタイミング | New-GitHubRelease成功時 |
| ロールバック条件 | なし（ドラフトリリースは手動削除） |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 数個のリリース（Release/Preview等） |
| 目標処理時間 | 数分（アップロード時間に依存） |
| メモリ使用量上限 | 特に制限なし |

## 排他制御

同一バージョンのリリースが既に存在する場合はGitHub API側でエラーとなる。同時実行の制御は行っていない。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| Verbose | アセット解析時 | "Cracking Preinstall Kit ...", "Found inner bundle ...", "Parsing AppxManifest.xml" |
| Verbose | リリース作成時 | "Preparing release ...", "Will create tag ...", "Uploading ..." |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 特になし | N/A | N/A |

## 備考

- SupportsShouldProcess に対応しており、-WhatIf でドライランが可能
- ブランディング判定はパッケージ名に基づく（Microsoft.WindowsTerminal → Release、Microsoft.WindowsTerminalPreview → Preview等）
- アセットは「理想的ファイル名」にリネームされてアップロードされる
- Assetクラス、Releaseクラス、ReleaseConfigクラスのオブジェクト指向設計を採用している
- Previewリリースは PreRelease フラグが true で作成される
