# バッチ設計書 9-.github/workflows/bisects.yml

## 概要

本ドキュメントは、GitHub Actionsのbisect実行ワークフロー設定ファイル `.github/workflows/bisects.yml` の設計仕様を定義するものである。

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

このバッチは、GitHub Actionsを使用してIssueコメントから「!nim」コマンドでgit bisectを自動実行するワークフローである。Nimコンパイラのバグを報告する際に、バグが導入されたコミットを自動的に特定することで、バグ修正の効率を大幅に向上させる。

**業務上の目的・背景**：Nimコンパイラのバグを修正する際、バグが導入されたコミットを特定することは非常に重要である。git bisectは手動で行うと時間がかかる作業だが、このワークフローにより、Issue報告者やメンテナがコメントで「!nim」コマンドを入力するだけで、Linux/Windows/macOSの各プラットフォームで自動的にbisectが実行され、原因コミットが特定される。

**バッチの実行タイミング**：
- Issueコメントが作成された時（`issue_comment` イベント、`created` タイプ）
- コメントが「!nim 」で始まる場合
- Issue（PRではない）に対するコメントの場合
- コメント投稿者が `NONE` 以外（リポジトリに関連がある）の場合

**主要な処理内容**：
1. リポジトリのチェックアウト
2. Windows環境でのOpenSSLインストール（必要に応じて）
3. Nimのdevelバージョンをセットアップ
4. nimrun-actionを使用してbisect実行
5. 結果をIssueに自動でコメント

**前後の処理との関連**：このワークフローは外部アクション `jiro4989/setup-nim-action` と `juancarlospaco/nimrun-action` に依存している。コメント内容によってプラットフォームが選択され、該当するプラットフォームでのみ実行される。

**影響範囲**：bisect実行結果がIssueコメントとして投稿される。これにより、バグ原因のコミットが自動的に特定され、開発者がバグ修正に着手しやすくなる。

## バッチ種別

CI/CD（バグ原因特定自動化）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | Issueコメント時 |
| 実行時刻 | コメント投稿タイミング |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | issue_comment (created + "!nim " prefix) |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| GitHub Actions | リポジトリでGitHub Actionsが有効化されていること |
| GITHUB_TOKEN | bisect結果のコメント投稿に必要なシークレット |
| ランナー | GitHub提供のホステッドランナー（ubuntu-latest, windows-latest, macos-latest） |

### 実行可否判定

以下の条件をすべて満たす場合に実行される：
- `github.event_name == 'issue_comment'`
- コメントが「!nim 」で始まる（`startsWith(github.event.comment.body, '!nim ')`）
- Issue（PRではない）に対するコメント（`github.event.issue.pull_request == null`）
- コメント投稿者が `NONE` 以外（`github.event.comment.author_association != 'NONE'`）

さらに、プラットフォーム固有の条件：
- Linux: コメントに `-d:linux` が含まれる、またはOS指定がない場合
- Windows: コメントに `-d:windows` が含まれる場合
- macOS: コメントに `-d:osx` が含まれる場合

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| platform | マトリクス | Yes | - | 実行プラットフォーム（ubuntu-latest, windows-latest, macos-latest） |
| github-token | シークレット | Yes | - | GitHub API認証トークン |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| Issueコメント | テキスト | 「!nim」で始まるコマンドとNimコード |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| Issueコメント | Markdown | bisect実行結果 |

### 出力ファイル仕様

該当なし（結果はIssueコメントとして出力）

## 処理フロー

### 処理シーケンス

```
1. トリガー判定
   └─ issue_comment created、!nimプレフィックス、Issue（非PR）、非NONEユーザー
2. リポジトリチェックアウト
   └─ actions/checkout@v5
3. Windows環境設定（Windowsのみ）
   └─ OpenSSL 1.1.1.0インストール
4. Nimセットアップ
   └─ setup-nim-action@v1 (devel)
5. プラットフォーム判定
   └─ コメント内の -d:linux/-d:windows/-d:osx で判定
6. nimrun-action実行
   └─ bisect自動実行
7. 結果投稿
   └─ Issueへコメント投稿
```

### フローチャート

```mermaid
flowchart TD
    A[Issueコメント] --> B{!nim プレフィックス?}
    B -->|No| C[終了]
    B -->|Yes| D{Issue（非PR）?}
    D -->|No| C
    D -->|Yes| E{非NONEユーザー?}
    E -->|No| C
    E -->|Yes| F[リポジトリチェックアウト]
    F --> G{Windows?}
    G -->|Yes| H[OpenSSLインストール]
    G -->|No| I[Nimセットアップ]
    H --> I
    I --> J{プラットフォーム条件合致?}
    J -->|No| C
    J -->|Yes| K[nimrun-action実行]
    K --> L[結果をIssueに投稿]
    L --> C
```

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

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

該当なし（このバッチはデータベースを使用しない）

### テーブル別操作詳細

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | Nimセットアップ失敗 | ネットワークエラー等 | 再実行 |
| 1 | bisect失敗 | コードのコンパイルエラー等 | コードを修正してコメント再投稿 |
| 1 | OpenSSLインストール失敗 | Windows環境のエラー | CI環境を確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 手動（新しいコメント投稿） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

### 障害時対応

1. GitHub Actionsのログを確認
2. コメント内のNimコードを確認
3. プラットフォーム指定（-d:linux等）を確認
4. 必要に応じて新しいコメントで再試行

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | N/A（データベース不使用） |
| コミットタイミング | N/A |
| ロールバック条件 | N/A |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 最大3ジョブ（各プラットフォーム） |
| 目標処理時間 | bisect対象範囲による |
| メモリ使用量上限 | GitHub提供のホステッドランナー依存 |

## 排他制御

- 各コメントに対して独立したワークフローが実行される
- 同一Issueへの複数コメントは並列で処理される可能性がある
- `fail-fast: false` により、一つのプラットフォームが失敗しても他は継続

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| セットアップログ | Nimインストール時 | インストール進捗 |
| bisectログ | bisect実行時 | 各コミットのテスト結果 |
| 結果ログ | bisect完了時 | 原因コミットの特定結果 |
| エラーログ | エラー発生時 | 失敗原因の詳細 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ワークフロー実行状態 | - | GitHub Actionsステータス |
| bisect成功/失敗 | - | Issueコメント |

## 備考

### 使用方法

Issueコメントに以下の形式で入力：

```
!nim c [オプション]
```

例：
```nim
!nim c -d:linux
echo "test"
```

### プラットフォーム指定

| 指定 | 実行プラットフォーム |
|------|---------------------|
| `-d:linux` | ubuntu-latest |
| `-d:windows` | windows-latest |
| `-d:osx` | macos-latest |
| 指定なし | ubuntu-latest（デフォルト） |

### 使用する外部アクション

| アクション | バージョン | 説明 |
|-----------|-----------|------|
| actions/checkout | v5 | リポジトリチェックアウト |
| jiro4989/setup-nim-action | v1 | Nim環境セットアップ（devel） |
| juancarlospaco/nimrun-action | nim | bisect実行 |

### author_association

`github.event.comment.author_association` が `NONE` 以外である必要がある。これにより、リポジトリに全く関連のないユーザーからのコメントでワークフローが実行されることを防ぐ。

有効な値：
- `OWNER`: リポジトリオーナー
- `MEMBER`: オーガニゼーションメンバー
- `COLLABORATOR`: コラボレーター
- `CONTRIBUTOR`: 過去にコントリビュートしたユーザー
- `FIRST_TIMER`: 初回コントリビューター
- `FIRST_TIME_CONTRIBUTOR`: 初回コントリビューター（別名）
- `MANNEQUIN`: マネキン（移行されたアカウント）

### OpenSSL注意事項

Windows環境では、OpenSSL 3.xで削除された `SSL_library_init` 関数が必要なため、OpenSSL 1.1.1.0をインストールしている。
