# バッチ設計書 8-.github/workflows/ci_publish.yml

## 概要

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

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

このバッチは、GitHub Actionsを使用してプルリクエストのマージ後にORCブートコンパイラのメモリ使用量を追跡するワークフローである。PRがマージされた際に自動的に実行され、コンパイラのメモリ効率を継続的に監視し、結果をPRにコメントとして投稿する。

**業務上の目的・背景**：Nimコンパイラ（特にORC GC使用時）のメモリ使用量は、コンパイラの品質指標の一つである。PRのマージによってメモリ使用量が増加していないかを継続的に監視することで、パフォーマンスの劣化を早期に検出できる。この情報は開発者がコンパイラの効率性を維持するための重要なフィードバックとなる。

**バッチの実行タイミング**：
- プルリクエストがマージされた時（`pull_request_target` イベントの `closed` タイプ、かつ `merged == true`）

**主要な処理内容**：
1. リポジトリのチェックアウト
2. Node.js のインストール
3. Linux amd64 環境での依存関係インストール
4. csourcesからのNimコンパイラビルド
5. kochビルドとNimコンパイラのリリースビルド
6. `ci/action.nim` を実行してメモリ使用量を測定
7. 結果を `ci/nimcache/results.txt` に出力
8. GitHub APIを使用してPRにコメントを投稿

**前後の処理との関連**：このワークフローは `ci/funs.sh` のユーティリティ関数に依存している。また、`ci/action.nim` がメモリ使用量測定の実際の処理を行う。測定結果はGitHub APIを通じてPRのコメントとして投稿される。

**影響範囲**：マージされたPRに対してメモリ使用量の情報がコメントとして追加される。この情報は参照目的であり、リポジトリの他の部分には影響しない。

## バッチ種別

CI/CD（パフォーマンス監視・レポート）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | PRマージ時 |
| 実行時刻 | PRマージタイミング |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | pull_request_target (closed + merged) |

## 実行条件

### 前提条件

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

### 実行可否判定

- PRがマージされた場合のみ実行（`github.event.pull_request.merged == true`）
- 単にPRがクローズされただけの場合は実行されない

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| os | マトリクス | Yes | ubuntu-22.04 | ランナーのOSイメージ |
| cpu | マトリクス | Yes | amd64 | CPUアーキテクチャ |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| config/build_config.txt | テキスト | csourcesのバージョン情報 |
| ci/funs.sh | シェルスクリプト | ユーティリティ関数 |
| ci/action.nim | Nimソース | メモリ使用量測定処理 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| ci/nimcache/results.txt | テキスト | メモリ使用量測定結果 |
| PRコメント | Markdown | GitHubのPRコメント |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | ci/nimcache/results.txt |
| 出力先 | ci/nimcache/ |
| 文字コード | UTF-8 |
| 区切り文字 | N/A |

## 処理フロー

### 処理シーケンス

```
1. リポジトリチェックアウト
   └─ fetchDepth: 2
2. Node.jsインストール
   └─ デフォルトバージョン
3. 依存関係インストール（Linux amd64）
   └─ apt-fast install（libcurl, libgc, valgrind等）
4. PATH設定
   └─ bin/ をPATHに追加
5. システム情報出力
   └─ nimCiSystemInfo
6. csourcesビルド
   └─ nimBuildCsourcesIfNeeded
7. kochビルド
   └─ nim c koch
8. Nimコンパイラビルド
   └─ ./koch boot -d:release -d:nimStrictMode --lib:lib
9. メモリ使用量測定
   └─ nim c -r -d:release ci/action.nim
10. PRへコメント投稿
    └─ GitHub APIでresults.txtの内容を投稿
```

### フローチャート

```mermaid
flowchart TD
    A[PR マージ] --> B{merged?}
    B -->|No| C[終了]
    B -->|Yes| D[リポジトリチェックアウト]
    D --> E[Node.jsインストール]
    E --> F[依存関係インストール]
    F --> G[PATH設定]
    G --> H[システム情報出力]
    H --> I[csourcesビルド]
    I --> J[kochビルド]
    J --> K[Nimコンパイラビルド]
    K --> L[メモリ使用量測定]
    L --> M[results.txt出力]
    M --> N[PRへコメント投稿]
    N --> C
```

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

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

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

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | ビルドエラー | コンパイル失敗 | ログを確認して修正 |
| 1 | 測定エラー | ci/action.nim失敗 | action.nimの実装を確認 |
| 1 | API呼び出しエラー | GitHub API失敗 | 権限設定を確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | GitHub Actions設定に依存 |
| リトライ間隔 | 手動での再実行 |
| リトライ対象エラー | 一時的なネットワークエラー等 |

### 障害時対応

1. GitHub Actionsのログを確認
2. 失敗したステップを特定
3. results.txt の生成に失敗した場合、ci/action.nim を確認
4. コメント投稿に失敗した場合、GITHUB_TOKENの権限を確認

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1ジョブ（PRマージごと） |
| 目標処理時間 | 制限なし（タイムアウト設定なし） |
| メモリ使用量上限 | GitHub提供のホステッドランナー依存 |

## 排他制御

- 各PRマージイベントに対して独立したワークフローが実行される
- 同一PRへの複数マージは発生しないため、競合は発生しない

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| システム情報 | ワークフロー開始時 | nimCiSystemInfo |
| コマンドログ | 各ステップ実行時 | 実行コマンドと結果 |
| メモリ使用量 | 測定完了時 | ci/nimcache/results.txt |
| エラーログ | エラー発生時 | 失敗原因の詳細 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ワークフロー実行状態 | - | GitHub Actionsステータス |
| メモリ使用量増加 | - | PRコメント（人的レビュー） |

## 備考

### トリガー詳細

このワークフローは `pull_request_target` イベントを使用している。これは通常の `pull_request` とは異なり、ベースリポジトリのコンテキストで実行される。これにより、フォークからのPRでも `GITHUB_TOKEN` を使用してコメントを投稿できる。

### nimStrictMode

`-d:nimStrictMode` フラグは、コンパイラのビルド時により厳格なチェックを有効にするオプションである。メモリ使用量の正確な測定のために使用される。

### GitHub Script アクション

コメント投稿には `actions/github-script@v7` を使用している。このアクションはJavaScriptコードを直接実行でき、GitHub REST APIを簡単に呼び出せる。

```javascript
const fs = require('fs');
const data = fs.readFileSync('ci/nimcache/results.txt', 'utf8');
github.rest.issues.createComment({
  issue_number: context.issue.number,
  owner: context.repo.owner,
  repo: context.repo.repo,
  body: data
})
```

### 依存関係

| パッケージ | 説明 |
|-----------|------|
| libcurl4-openssl-dev | HTTP通信ライブラリ |
| libgc-dev | Boehmガベージコレクタ |
| libsdl1.2-dev | SDLライブラリ |
| libsfml-dev | SFMLライブラリ |
| valgrind | メモリデバッグツール |
| libc6-dbg | Cライブラリデバッグシンボル |
| libblas-dev | BLAS数値計算ライブラリ |
| xorg-dev | X Window Systemライブラリ |
