# バッチ設計書 40-Release Builds（release.yml）

## 概要

本ドキュメントは、mrubyプロジェクトにおけるGitHub Actionsワークフロー `Release Builds`（release.yml）のバッチ設計書である。タグpush時にソースコードをzip/tar.gz/tar.xzでパッケージングしGitHubリリースを作成するCI/CDパイプラインについて記述する。

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

`Release Builds` ワークフローは、GitHub Actionsで定義されたリリース自動化パイプラインであり、セマンティックバージョニング形式のタグ（`*.*.*`）がpushされた際に自動実行され、ソースコードを複数のアーカイブ形式でパッケージングし、GitHubリリースをドラフトとして作成する。

**業務上の目的・背景**：mrubyの新バージョンリリース時に、ソースコードパッケージの作成とGitHubリリースの公開を自動化する。手動でのパッケージング作業を排除し、リリースプロセスの信頼性と効率を向上させる。ドラフトリリースとして作成されるため、メンテナが内容を確認してから公開できる。

**バッチの実行タイミング**：セマンティックバージョニング形式（`*.*.*`）のタグがGitHubリポジトリにpushされた時に自動実行される。mruby/mrubyリポジトリでのみ実行される。

**主要な処理内容**：
1. コードチェックアウト
2. `git archive` コマンドでソースコードをzip、tar.gz、tar.xzの3形式でアーカイブ
3. SHA256チェックサムファイルの生成
4. `softprops/action-gh-release` を使用してGitHubドラフトリリースを作成
5. NEWSファイルをリリースノートの本文として使用
6. タグ名に `-rc` が含まれる場合はプレリリースとしてマーキング

**前後の処理との関連**：本ワークフローはタグpush時のみ実行される独立したパイプラインである。リリース前にNo.38 Build & Test（build.yml）で全テストが通過していることが前提となる。

**影響範囲**：GitHubリリースにドラフトが作成され、パッケージファイルがアップロードされる。リポジトリの`contents: write`権限が必要。

## バッチ種別

CI/CDパイプライン（リリース・パッケージング）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動（タグpush時） |
| 実行時刻 | イベント発生時 |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | push（tags: `*.*.*` パターン） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| GitHub Actions | GitHubリポジトリでActionsが有効であること |
| リポジトリ | `mruby/mruby` リポジトリであること（`github.repository == 'mruby/mruby'` 条件） |
| タグ形式 | セマンティックバージョニング形式（`*.*.*`）のタグであること |
| ランナー | ubuntu-22.04のランナーが利用可能であること |
| NEWSファイル | プロジェクトルートにNEWSファイルが存在すること |

### 実行可否判定

以下の2つの条件を両方満たす場合にのみ実行される：
1. `*.*.*` パターンに一致するタグがpushされた
2. `github.repository == 'mruby/mruby'` である（フォークリポジトリでは実行されない）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| GITHUB_REF_NAME | 環境変数 | Yes | （自動設定） | タグ名（バージョン番号） |
| GITHUB_REF | 環境変数 | Yes | （自動設定） | Gitリファレンス |
| GITHUB_SHA | 環境変数 | Yes | （自動設定） | コミットSHA |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| .github/workflows/release.yml | YAML | ワークフロー定義 |
| mrubyソースコード一式 | 各種 | アーカイブ対象 |
| NEWS | テキスト | リリースノート本文 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| GitHub Releases | ドラフトリリース | リリース情報とアーカイブファイル |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | mruby-{タグ名}.zip、mruby-{タグ名}.tar.gz、mruby-{タグ名}.tar.xz、mruby-{タグ名}.sha256 |
| 出力先 | GitHub Releasesのアセット |
| 文字コード | N/A（バイナリアーカイブ） |
| 区切り文字 | N/A |

## 処理フロー

### 処理シーケンス

```
1. トリガー検知
   └─ *.*.*パターンのタグpushイベントの検知
2. リポジトリ条件チェック
   └─ github.repository == 'mruby/mruby' を確認
3. コードチェックアウト
   └─ actions/checkout@v6でリポジトリをクローン
4. パッケージング
   4a. packagesディレクトリを作成
   4b. git archive --format zip でzipアーカイブを生成
   4c. git archive --format tar.gz でtar.gzアーカイブを生成
   4d. tar.gzをgunzip + xzでtar.xzアーカイブを生成
   4e. sha256sum で全パッケージのチェックサムを生成
5. GitHubリリース作成
   └─ softprops/action-gh-release@v2でドラフトリリースを作成
   └─ NEWSファイルをbody_pathとして使用
   └─ タグ名に-rcが含まれる場合はプレリリースとしてマーキング
   └─ packages/*を添付ファイルとしてアップロード
```

### フローチャート

```mermaid
flowchart TD
    A["タグ push イベント (*.*.*パターン)"] --> B{"github.repository == 'mruby/mruby'?"}
    B -->|いいえ| C[スキップ]
    B -->|はい| D[コードチェックアウト]
    D --> E[packagesディレクトリ作成]
    E --> F[git archive でzipアーカイブ生成]
    F --> G[git archive でtar.gzアーカイブ生成]
    G --> H[tar.gzからtar.xzアーカイブ生成]
    H --> I[SHA256チェックサム生成]
    I --> J{"タグ名に-rcを含む?"}
    J -->|はい| K[プレリリースとしてドラフト作成]
    J -->|いいえ| L[通常のドラフトリリース作成]
    K --> M[packages/*をアセットとしてアップロード]
    L --> M
    M --> N[正常終了]
    C --> O[バッチ終了]
    N --> O
```

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

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

本バッチではデータベース操作は行わない。

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

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ジョブ失敗 | アーカイブ生成失敗 | git archiveコマンドのエラー | タグの参照が正しいか確認 |
| ジョブ失敗 | チェックサム生成失敗 | sha256sumコマンドのエラー | パッケージファイルの生成を確認 |
| ジョブ失敗 | リリース作成失敗 | GitHub APIエラー | パーミッションやリリース設定を確認 |
| ジョブ失敗 | タイムアウト | 処理時間超過（10分） | ネットワーク状態を確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（GitHub Actions標準動作、手動で再実行可能） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

### 障害時対応

ジョブ失敗時はGitHub Actionsのログを確認し、失敗したステップを特定する。リリースが部分的に作成された場合は、GitHub UIからドラフトリリースを手動で削除してから再実行する。

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 4ファイル（zip、tar.gz、tar.xz、sha256） |
| 目標処理時間 | 10分以内（timeout-minutes: 10） |
| メモリ使用量上限 | GitHub Actionsランナーのデフォルト値 |

## 排他制御

同一タグに対する複数のリリースワークフロー実行は想定されない。タグのpushは通常1回のみ発生する。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | ジョブ開始時 | チェックアウト情報（タグ名、コミットSHA） |
| 進捗ログ | パッケージング中 | 各アーカイブ形式の生成状況 |
| 終了ログ | リリース作成完了時 | ドラフトリリースの作成完了情報 |
| エラーログ | エラー発生時 | エラー詳細 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ジョブ実行時間 | 10分 | GitHub Actions UI |
| ジョブ失敗 | 1件以上 | GitHub通知 |

## 備考

- `permissions: read-all` がトップレベルで設定され、sourceジョブで `contents: write` にオーバーライドされる
- `github.repository == 'mruby/mruby'` 条件により、フォークリポジトリでは実行されない
- `fail-fast: false` が設定されているが、現時点ではマトリクスは使用されていない
- `softprops/action-gh-release@v2` でドラフトリリースを作成する
- タグ名に `-rc` が含まれる場合は `prerelease: true` が設定される
- `body_path: NEWS` でNEWSファイルの内容がリリースノートとして使用される
- `git archive` で `--prefix "$packagename/"` を使用し、アーカイブ内にバージョン名のプレフィックスディレクトリが付与される
- アーカイブファイル名の形式: `mruby-{タグ名}.{zip|tar.gz|tar.xz|sha256}`
- ubuntu-22.04で実行される
