# バッチ設計書 2-version.ts

## 概要

本ドキュメントは、OpenCodeプロジェクトのGitHubリリース作成バッチ（version.ts）の設計仕様を定義する。このバッチはチェンジログを生成し、ドラフト状態のGitHubリリースを作成する。

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

このバッチは、新バージョンのリリース準備として、GitHubリリースのドラフトを作成し、リリースノートを自動生成する。changelog.tsスクリプトと連携して、前回リリースからのコミット履歴を解析し、人間が読みやすい形式のリリースノートを生成する。

**業務上の目的・背景**：ソフトウェアリリースにおいて、リリースノートの作成は重要だが手間のかかる作業である。本バッチは、コミット履歴からAIを活用してリリースノートを自動生成し、GitHubリリースのドラフトを作成することで、リリースプロセスを効率化する。これにより、一貫性のあるリリースノートを迅速に作成できる。

**バッチの実行タイミング**：publish.ymlワークフロー内で、パブリッシュ処理の前段階として実行される。メインブランチへのプッシュ時に自動実行され、手動でも実行可能。

**主要な処理内容**：
1. 現在のバージョン番号を取得（Script.version）
2. GitHub APIから最新リリースのタグを取得
3. 前回リリースからHEADまでのコミット履歴を解析
4. AIを使用してリリースノートを生成（buildNotes関数）
5. リリースノートを一時ファイルに保存
6. gh CLIでドラフトリリースを作成
7. リリース情報（databaseId、tagName）をGitHub Actions出力に設定

**前後の処理との関連**：changelog.tsの関数（buildNotes、getLatestRelease）を呼び出して使用する。後続のpublish.tsスクリプトで、作成されたドラフトリリースが公開される。

**影響範囲**：GitHubリポジトリのリリースページに新しいドラフトリリースが作成される。GitHub Actions出力変数が設定され、後続ジョブで使用される。

## バッチ種別

リリース自動化 / リリースノート生成

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動（随時） |
| 実行時刻 | 該当なし |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | GitHub Actions（publish.ymlワークフロー内）、手動実行 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Script.version | リリースバージョン番号が設定されていること |
| Script.preview | プレビューモードフラグが設定されていること |
| Script.channel | リリースチャンネル（beta等）が設定されていること |
| GH_REPO | GitHubリポジトリ名が環境変数に設定されていること |
| RUNNER_TEMP | GitHub Actionsの一時ディレクトリパス（未設定時は/tmp） |
| GITHUB_OUTPUT | GitHub Actions出力ファイルパス |
| gh CLI認証 | GitHubへの書き込み権限があること |

### 実行可否判定

Script.previewがfalseの場合は通常リリース処理、trueかつScript.channelが"beta"の場合はベータリリース処理を行う。それ以外の場合はリリース作成をスキップし、出力変数のみ設定する。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| Script.version | string | Yes | - | リリースバージョン番号 |
| Script.preview | boolean | No | false | プレビューモードフラグ |
| Script.channel | string | No | - | リリースチャンネル |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| GitHub Releases API | JSON | 最新リリース情報の取得 |
| Git履歴 | コミットログ | リリースノート生成用 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| GitHub Releases | ドラフトリリース | バージョンタグ付きドラフトリリース |
| GITHUB_OUTPUT | キー=値形式 | version、release、tag、repo変数 |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | opencode-release-notes.txt |
| 出力先 | $RUNNER_TEMP または /tmp |
| 文字コード | UTF-8 |
| 区切り文字 | 改行区切りテキスト |

## 処理フロー

### 処理シーケンス

```
1. バージョン番号の取得
   └─ Script.versionから現在のバージョンを取得

2. 出力配列の初期化
   └─ version変数を設定

3. プレビューモード判定
   └─ Script.previewの値で分岐

4. 通常リリースの場合
   ├─ 最新リリースタグの取得（getLatestRelease）
   ├─ リリースノート生成（buildNotes）
   ├─ 一時ファイルへの書き込み
   ├─ gh release createでドラフト作成
   └─ リリース情報の取得（gh release view）

5. ベータリリースの場合
   ├─ gh release createでドラフト作成（リポジトリ指定）
   └─ リリース情報の取得

6. 出力変数の設定
   └─ GITHUB_OUTPUTファイルへの書き込み
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[version変数設定]
    B --> C{Script.preview?}
    C -->|false| D[getLatestRelease]
    D --> E[buildNotes]
    E --> F[リリースノートファイル作成]
    F --> G[gh release create --draft]
    G --> H[gh release view]
    C -->|true| I{channel == beta?}
    I -->|Yes| J[gh release create --draft with repo]
    J --> K[gh release view with repo]
    I -->|No| L[スキップ]
    H --> M[output配列に追加]
    K --> M
    L --> M
    M --> N[repo変数追加]
    N --> O{GITHUB_OUTPUT存在?}
    O -->|Yes| P[ファイル書き込み]
    O -->|No| Q[スキップ]
    P --> R[process.exit 0]
    Q --> R
    R --> S[バッチ終了]
```

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

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

本バッチはデータベース操作を行わない。GitHub APIへのリクエストのみ。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | API呼び出し失敗 | getLatestRelease失敗 | ネットワーク確認、GitHub API状態確認 |
| - | リリースノート生成失敗 | buildNotes内エラー | changelog.ts参照、AI API確認 |
| - | ファイル書き込み失敗 | 一時ディレクトリ権限不足 | RUNNER_TEMP確認 |
| - | gh release create失敗 | 認証エラー/重複タグ | 認証確認、既存リリース削除 |
| - | gh release view失敗 | リリース未作成 | create成功確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（即時失敗） |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

1. リリース作成失敗：gh release deleteで既存のドラフトを削除し再実行
2. リリースノート生成失敗：手動でリリースノートを作成し、gh release editで更新
3. 出力変数設定失敗：後続ジョブで使用する変数を手動設定

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | なし |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし（ドラフトは手動削除可能） |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1リリース |
| 目標処理時間 | 2分以内（AI処理含む） |
| メモリ使用量上限 | 特に制限なし |

## 排他制御

同一バージョンのリリースは重複作成不可。既存タグが存在する場合はgh release createが失敗する。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 進捗ログ | changelog生成時 | buildNotes内のログ |
| 出力ログ | 変数設定時 | GITHUB_OUTPUTへの書き込み内容 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ワークフロー実行結果 | 失敗時 | GitHub Actions通知 |
| リリース作成状態 | 失敗時 | GitHub Actions通知 |

## 備考

- process.exit(0)で明示的に正常終了している
- リリースノートが空の場合は"No notable changes"がデフォルトメッセージとなる
- ベータリリースの場合はリリースノートなしでドラフトが作成される
- GH_REPO環境変数はベータリリース時のみ使用される
