# バッチ設計書 9-release-note-generator

## 概要

本ドキュメントは、リリースノートを生成するスクリプト「release-note-generator」の設計仕様を記載したものです。

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

このバッチは、GitHub API経由でPull Request情報を取得し、対話形式でリリースノートファイルを作成するTypeScriptスクリプトです。開発者がPRを作成する際に、対応するリリースノートエントリを効率的に作成できます。

**業務上の目的・背景**：オープンソースプロジェクトにおいて、リリースノートはユーザーに対する重要な情報伝達手段です。各PRに対応するリリースノートエントリを標準化された形式で管理することで、リリース時に自動的に整理されたリリースノートを生成できます。このスクリプトにより、開発者はPR番号、カテゴリ、要約などを対話形式で入力し、一貫した形式のリリースノートファイルを自動生成できます。手動でのファイル作成に比べて、形式の統一とエラーの削減が期待できます。

**バッチの実行タイミング**：手動実行。PRを作成した後、リリースノートエントリを追加する際に開発者が実行します。

**主要な処理内容**：
1. GitHub CLIでユーザー名を取得（オプション）
2. 現在のブランチに対応するPRを検索
3. GitHub APIで最新のPR/Issue番号を取得
4. 対話形式で以下の情報を入力：
   - GitHubユーザー名（カンマ区切りで複数可）
   - PR番号
   - リリースノートタイプ（Features/Enhancements/Bugfixes/Maintenance）
   - 要約（1行説明）
5. リリースノートファイルを生成（上書き確認あり）

**前後の処理との関連**：PRの作成後に実行されます。生成されたリリースノートファイルは、リリースプロセスでリリースノートドキュメントに統合されます。

**影響範囲**：`upcoming-release-notes/`ディレクトリにリリースノートファイルを作成

## バッチ種別

開発支援 / ドキュメント生成

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（PR作成時） |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Node.js環境 | Node.js 22以上がインストールされていること |
| ts-node | TypeScript実行環境が利用可能であること |
| GitHub CLI（推奨） | ghコマンドがインストールされていると自動で情報取得可能 |
| ネットワーク接続 | GitHub APIへのアクセスが可能であること |

### 実行可否判定

常に実行可能。GitHub CLIがない場合でも、ユーザー名を手動入力することで動作します。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | 対話形式で入力 |

### 対話入力項目

| 項目 | 型 | 必須 | デフォルト値 | 説明 |
|-----|-----|-----|-------------|------|
| githubUsername | string | Yes | gh api user取得値 | カンマ区切りで複数指定可 |
| pullRequestNumber | number | Yes | 最新Issue番号+1または既存PR番号 | PR番号 |
| releaseNoteType | select | Yes | なし | Features/Enhancements/Bugfixes/Maintenance |
| oneLineSummary | string | Yes | PRタイトル | 変更の要約 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| GitHub API | JSON | PR情報、Issue番号取得 |
| git | コマンド | 現在のブランチ名取得 |
| gh CLI | コマンド | ユーザー名取得（オプション） |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| upcoming-release-notes/{PR番号}.md | Markdown | リリースノートエントリ |
| 標準出力 | テキスト | 進捗・結果メッセージ |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | {PR番号}.md |
| 出力先 | ./upcoming-release-notes/ |
| 文字コード | UTF-8 |
| 区切り文字 | 該当なし |

### 出力ファイル形式

```markdown
---
category: {Features|Enhancements|Bugfixes|Maintenance}
authors: [{username1}, {username2}]
---

{oneLineSummary}
```

## 処理フロー

### 処理シーケンス

```
1. ユーザー名取得
   └─ gh api user --jq '.login'（失敗時は空文字）
2. アクティブPR検索
   ├─ git rev-parse --abbrev-ref HEADでブランチ名取得
   └─ GitHub APIでuser:branchのPRを検索
3. PR番号初期値決定
   ├─ 既存PRあり: そのPR番号
   └─ なし: 最新Issue番号+1（getNextPrNumber）
4. 対話入力
   ├─ GitHubユーザー名
   ├─ PR番号
   ├─ リリースノートタイプ
   └─ 要約
5. ファイル存在確認
   └─ 既存ファイルあり: 上書き確認
6. ファイル生成
   └─ upcoming-release-notes/{PR番号}.mdを作成
7. 完了メッセージ
   └─ 「Release note generated successfully: {filepath}」
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[gh api userでユーザー名取得]
    B --> C[getActivePrでPR検索]
    C --> D{既存PRあり?}
    D -->|Yes| E[PR番号を初期値に設定]
    D -->|No| F[getNextPrNumberで番号取得]
    E --> G[対話入力開始]
    F --> G
    G --> H[ユーザー名入力]
    H --> I[PR番号入力]
    I --> J[リリースノートタイプ選択]
    J --> K[要約入力]
    K --> L{全項目入力済み?}
    L -->|No| M[エラー終了 exit 1]
    L -->|Yes| N{ファイル存在?}
    N -->|Yes| O[上書き確認]
    O -->|No| P[終了 exit 1]
    O -->|Yes| Q[ファイル書き込み]
    N -->|No| Q
    Q --> R{書き込み成功?}
    R -->|No| S[エラー終了 exit 1]
    R -->|Yes| T[成功メッセージ表示]
    T --> U[バッチ終了]
```

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

該当なし。このスクリプトはデータベース操作を行いません。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | input-error | 必須項目が未入力 | 全ての質問に回答 |
| 1 | api-error | GitHub API呼び出し失敗 | ネットワーク接続を確認 |
| 1 | write-error | ファイル書き込み失敗 | ディレクトリ権限を確認 |
| 1 | cancel | 上書き確認でキャンセル | 必要に応じて再実行 |

### リトライ仕様

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

### 障害時対応

1. gh CLIエラー：GitHub CLIをインストールするか、ユーザー名を手動入力
2. APIエラー：ネットワーク接続を確認、GitHub APIのレート制限を確認
3. ファイル書き込みエラー：出力ディレクトリの存在と権限を確認

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

該当なし。

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1ファイル |
| 目標処理時間 | 数秒（対話時間除く） |
| メモリ使用量上限 | 特に制限なし |

## 排他制御

排他制御なし。同じPR番号のファイルを複数人が同時に作成しようとした場合、後から保存した内容で上書きされます。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 情報ログ | PR検出時 | 「Found potentially matching PR {number}: {title}」 |
| 警告ログ | gh CLI未設定時 | GitHub CLI導入の推奨メッセージ |
| 警告ログ | API呼び出し失敗時 | 「error fetching from github pulls api:」 |
| 成功ログ | ファイル生成時 | 「Release note generated successfully: {filepath}」 |
| エラーログ | 入力不足時 | 「All questions must be answered. Exiting」 |
| エラーログ | 書き込み失敗時 | 「Failed to write release note file:」 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 終了コード | 0以外 | 実行者（手動実行のため） |

## 備考

- 実行コマンド: `yarn generate:release-notes`
- スクリプトファイル: `bin/release-note-generator.ts`
- TypeScriptで実装、ts-nodeで実行
- promptsライブラリを使用した対話UI
- GitHub CLIがインストールされていると、ユーザー名とPR情報を自動取得
- リリースノートタイプは絵文字付きで選択：
  - Features
  - Enhancements
  - Bugfixes
  - Maintenance
- 生成されたファイルは`upcoming-release-notes/`ディレクトリに配置
- リリース時に全ファイルを統合してリリースノートドキュメントを生成
