# バッチ設計書 10-CI-sample.yml

## 概要

本ドキュメントは、libuvプロジェクトのドキュメント内サンプルコードビルド確認ワークフロー `.github/workflows/CI-sample.yml` の設計仕様を定義する。

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

`CI-sample.yml` は、GitHub Actionsで実行されるドキュメント内サンプルプログラムのビルド検証用CI/CDワークフローである。macOS、Ubuntu、Windowsの3プラットフォーム上で、docs/code/配下のサンプルプログラムがコンパイル可能であることを自動検証する。

**業務上の目的・背景**：libuvのドキュメントに掲載されているサンプルプログラム（helloworld、dns、spawn等）は、ライブラリのAPIの使い方を示す重要な学習資料である。libuvのAPI変更やリファクタリングにより、これらのサンプルがコンパイル不能になる回帰バグを早期に検出する必要がある。本ワークフローは、サンプルコードの継続的なコンパイル可能性を保証する。

**バッチの実行タイミング**：Pull Request作成/更新時（docs/配下を含むパス変更時）、およびバージョンブランチ（v[0-9].*）やmasterブランチへのpush時に自動実行される。

**主要な処理内容**：
1. macOS、Ubuntu、Windowsの3環境マトリクスでの実行
2. docs/code/build ディレクトリの作成
3. CMake構成（docs/code/CMakeLists.txt を処理）
4. CMakeビルド（全サンプルプログラムのコンパイル）

**前後の処理との関連**：docs/code/CMakeLists.txt（No.5）を使用してサンプルのビルド設定を読み込む。CMakeLists.txt（No.4）をサブディレクトリとして間接的に参照し、libuv本体（uv_a）をビルドする。

**影響範囲**：ドキュメント内サンプルプログラムのコンパイル可能性の検証結果に影響する。PRマージ可否の判断基準の一つとなる。

## バッチ種別

CI/CDワークフロー（サンプルコードビルド検証）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動（PR作成/更新、push） |
| 実行時刻 | イベント発生時 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | pull_request（パスフィルタ付き）、push（v[0-9].*、master） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| GitHub Actionsランナー | macos-latest、ubuntu-latest、windows-latest が利用可能であること |
| CMake | ランナーにCMakeがプリインストールされていること |
| Cコンパイラ | ランナーにCコンパイラがプリインストールされていること |

### 実行可否判定

パスフィルタにより、docs/配下の変更が含まれる場合はワークフローが実行される。ただし docs/code/ 配下の変更は常に実行される。隠しファイルのみの変更ではワークフローが実行されない（ただし本ワークフロー自身の変更は除く）。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| （ワークフロー入力なし） | - | - | - | トリガーイベントにより自動実行 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| libuvリポジトリ全体 | Git | actions/checkout@v6 でチェックアウト |
| docs/code/CMakeLists.txt | CMake設定 | サンプルコードのビルド設定 |
| docs/code/{sample}/main.c | Cソースファイル | 各サンプルプログラムのソースコード |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| GitHub Actions ログ | テキスト | ビルド結果のログ |
| GitHub PR ステータスチェック | ステータス | 各ジョブの成功/失敗ステータス |

### 出力ファイル仕様

該当なし（CI/CDの実行結果はGitHub Actionsのインターフェースで確認。ビルド成果物はアーティファクトとしてアップロードされない）

## 処理フロー

### 処理シーケンス

```
1. checkout
   └─ actions/checkout@v6 でリポジトリをチェックアウト
2. setup
   └─ cmake -E make_directory でビルドディレクトリを作成
   └─ ${{runner.workspace}}/libuv/docs/code/build
3. configure
   └─ cmake .. でdocs/code/CMakeLists.txtを処理
   └─ working-directory: docs/code/build
4. build
   └─ cmake --build . で全サンプルプログラムをビルド
   └─ working-directory: docs/code/build
```

### フローチャート

```mermaid
flowchart TD
    A[ワークフロー開始] --> B[build ジョブ x3 プラットフォーム]
    B --> C[checkout]
    C --> D[cmake -E make_directory ビルドディレクトリ作成]
    D --> E[cmake .. 構成]
    E --> F[cmake --build . ビルド]
    F --> G{ビルド成功?}
    G -->|Yes| H[ジョブ成功]
    G -->|No| I[ジョブ失敗]
```

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

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

該当なし（本ワークフローはCI/CDパイプラインであり、データベースは使用しない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | CMake構成エラー | docs/code/CMakeLists.txtの構文エラーまたはlibuv本体のビルドエラー | CMake出力を確認し、設定を修正する |
| - | コンパイルエラー | サンプルプログラムがlibuvのAPI変更に追従していない場合 | サンプルコード（main.c）を最新APIに合わせて修正する |
| - | リンクエラー | libuv本体のビルドに失敗した場合 | ルートCMakeLists.txtの問題を調査する |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | ワークフローレベルでの自動リトライなし |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

`fail-fast: false` が設定されているため、一つのプラットフォームでビルドが失敗しても他のプラットフォームのテストは継続される。失敗時はGitHub ActionsのUIからビルドログを確認し、コンパイルエラーの原因を特定する。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1ジョブ x 3プラットフォーム、各ジョブで最大25個のサンプルをビルド |
| 目標処理時間 | 各ジョブ数分（libuv本体 + サンプルのビルド） |
| メモリ使用量上限 | GitHub Actions ランナーのデフォルトリソース |

## 排他制御

各ジョブは独立したランナーで並列実行される。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| CMake構成ログ | cmake構成時 | CMakeの構成出力（プラットフォーム検出結果等） |
| ビルドログ | cmake --build実行時 | 各サンプルプログラムのコンパイル・リンク結果 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ジョブ成功/失敗 | 1つでも失敗 | GitHub PRステータスチェック |

## 備考

- 本ワークフローはビルドのみを実行し、サンプルプログラムの実行テストは行わない
- パスフィルタにおいて `docs/code/**` は除外対象（`!docs/**`）の例外として明示的に含まれている
- Windows環境ではVisual Studioのデフォルトジェネレータが使用される（Ninja等の明示的指定なし）
- ビルドディレクトリは `${{runner.workspace}}/libuv/docs/code/build` に作成される
- テスト実行ステップは存在せず、コンパイル可否のみを検証する設計
