# バッチ設計書 3-build-and-test.yml

## 概要

本ドキュメントは、GitHub Actions CI/CDワークフロー `build-and-test.yml` の設計仕様を記載する。このワークフローはpush、pull_request、および日次スケジュールでHSLプロジェクトのビルドとテストを自動実行する。

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

`build-and-test.yml` は、HSL（Hack Standard Library）プロジェクトの継続的インテグレーション/継続的デリバリー（CI/CD）を実現するGitHub Actionsワークフローである。HHVMのnightlyビルドを使用し、Ubuntu環境で型チェックとテストを実行する。

**業務上の目的・背景**：HSLプロジェクトのコード品質を継続的に保証するため、コード変更時に自動的に型チェックとテストを実行する。また、HHVMのnightlyビルドに対する互換性を日次で検証することで、HHVM本体の変更によるHSLへの影響を早期に検出する。

**バッチの実行タイミング**：リポジトリへのpush時、pull_request作成・更新時、および日次スケジュール（毎日15:42 UTC）。

**主要な処理内容**：
1. リポジトリのチェックアウト（actions/checkout@v2）
2. HHVMのインストール（hhvm/actions/install-hack@master、nightlyバージョン）
3. HHVMバージョンの出力（デバッグ・記録用）
4. Watchmanのインストール（apt）
5. ロケールサポートのインストール（en_US, fr_FR, tr_TR, da_DK）
6. hh_clientによる型チェック
7. minitest.shによるテスト実行

**前後の処理との関連**：本ワークフローはGitHub Actionsによって自動トリガーされる。pull_requestイベントではマージ前のコードレビュープロセスの一部として機能し、テスト結果がpull_requestのステータスとして表示される。

**影響範囲**：GitHub Actions実行環境（Ubuntu仮想マシン）内でのみ実行される。リポジトリ自体への変更は行わない。テスト結果はGitHub UI上でコミット/PRステータスとして表示される。

## バッチ種別

CI/CD（継続的インテグレーション/継続的デリバリー）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動（push/pull_request）+ 日次スケジュール |
| 実行時刻 | 15:42 UTC（日次スケジュール） |
| 実行曜日 | 全曜日 |
| 実行日 | 毎日 |
| トリガー | push / pull_request / cron（42 15 * * *） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| GitHub Actions有効 | リポジトリでGitHub Actionsが有効であること |
| HHVM nightlyビルド | hhvm/actions/install-hack@masterでnightlyビルドが取得可能であること |
| Ubuntu環境 | ubuntu-latestランナーが利用可能であること |

### 実行可否判定

GitHub Actionsのトリガー条件（push、pull_request、schedule）を満たせば自動実行される。fail-fast: false設定により、一部のマトリックスが失敗しても他のマトリックスは継続実行される。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| matrix.os | ワークフロー変数 | Yes | ubuntu | 実行OS |
| matrix.hhvm | ワークフロー変数 | Yes | nightly | HHVMバージョン |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| リポジトリソースコード | Git | actions/checkout@v2でチェックアウト |
| HHVM nightlyビルド | APT/Debian package | hhvm/actions/install-hack@masterで取得 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| GitHub Actions ログ | テキスト | 各ステップの実行ログ |
| コミット/PRステータス | GitHub UI | 成功/失敗ステータス |

### 出力ファイル仕様

本ワークフローはファイル出力を行わない（GitHub Actions実行ログのみ）。

## 処理フロー

### 処理シーケンス

```
1. チェックアウト
   └─ actions/checkout@v2でリポジトリをチェックアウト
2. HHVM インストール
   └─ hhvm/actions/install-hack@masterでHHVM nightlyをインストール
3. バージョン確認
   └─ hhvm --versionでバージョン出力（デバッグ・記録用）
4. 依存パッケージインストール
   ├─ Watchmanインストール（apt install watchman）
   └─ ロケールインストール（en_US, fr_FR, tr_TR, da_DK）
5. 型チェック
   └─ hh_clientで型チェック実行
6. テスト実行
   └─ ./minitest.shでテスト実行
```

### フローチャート

```mermaid
flowchart TD
    A[ワークフロー開始] --> B[actions/checkout@v2]
    B --> C[hhvm/actions/install-hack@master]
    C --> D[hhvm --version]
    D --> E{matrix.os == ubuntu?}
    E -->|Yes| F[apt install watchman]
    E -->|No| G[スキップ]
    F --> H[apt install locales + locale-gen]
    G --> I[hh_client]
    H --> I
    I --> J{型チェック成功?}
    J -->|No| K[ワークフロー失敗]
    J -->|Yes| L[./minitest.sh]
    L --> M{テスト成功?}
    M -->|No| K
    M -->|Yes| N[ワークフロー成功]
```

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

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

本ワークフローはデータベース操作を行わない。

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| N/A | N/A | N/A | データベース操作なし |

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

N/A（データベース操作なし）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 失敗 | チェックアウト失敗 | リポジトリアクセス不可 | リポジトリ設定確認 |
| 失敗 | HHVMインストール失敗 | nightlyビルド取得不可 | hhvm/actionsの状態確認 |
| 失敗 | 型チェック失敗 | hh_clientがエラーを検出 | 型エラーの修正 |
| 失敗 | テスト失敗 | minitest.shが非ゼロ終了 | テストコードの修正 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（GitHub Actionsデフォルト） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

### 障害時対応

ワークフロー失敗時はGitHub Actions UIで失敗したステップのログを確認する。型チェック失敗の場合はhh_clientの出力を確認し、テスト失敗の場合はminitest.shの出力を確認する。

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1リポジトリ / 1マトリックス |
| 目標処理時間 | GitHub Actions無料枠内（通常数分〜十数分） |
| メモリ使用量上限 | GitHub Actionsランナーの制限に依存 |

## 排他制御

GitHub Actionsのコンカレンシー設定は明示的に行われていない。複数のpush/pull_requestが同時にトリガーされた場合、それぞれ独立したジョブとして並列実行される。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| ステップログ | 各ステップ実行時 | ステップ名と実行結果 |
| コマンド出力 | 各runステップ | コマンドの標準出力・標準エラー出力 |
| HHVMバージョン | Print HHVM versionステップ | hhvm --versionの出力 |
| 型チェック結果 | Typecheckステップ | hh_clientの出力 |
| テスト結果 | Run testsステップ | minitest.shの出力 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ワークフロー結果 | 失敗 | GitHub UI（コミット/PRステータス） |
| 日次ビルド | 失敗 | GitHub UI（Actionsタブ） |

## 備考

- ワークフロー名: "Continuous Integration"
- fail-fast: false 設定により、一部マトリックスの失敗が他のマトリックスの実行を停止しない
- 現在のマトリックス構成: ubuntu × nightly のみ（将来的に拡張可能な構造）
- ロケールサポート（en_US, fr_FR, tr_TR, da_DK）は国際化テストのために必要
- Watchmanはファイル監視のためにhh_clientが使用する
- 日次スケジュール（15:42 UTC）はHHVM nightlyビルドとの互換性を継続的に検証するため
