# バッチ設計書 9-releases.yml

## 概要

本ドキュメントは、serve-dプロジェクトにおけるリリースデプロイ用GitHub Actionsワークフロー `.github/workflows/releases.yml` のバッチ設計書である。

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

本バッチは、GitHubリリースの公開時に自動トリガーされるGitHub Actionsワークフローであり、各プラットフォーム向けにserve-dのリリースバイナリをビルド・バージョン検証し、リリースアセットとしてアップロードする。

**業務上の目的・背景**：serve-dの正式リリースを公開する際に、全プラットフォーム（Linux、Windows、macOS）向けのプリビルトバイナリを自動的に生成し、GitHubリリースのアセットとして添付する。バージョン整合性の検証を含むことで、リリースタグとバイナリのバージョンが一致していることを保証する。ナイトリービルド（No.8）とは異なり、リリースビルドのみ（release-debugではなくrelease）を使用し、バージョン検証が追加されている。

**バッチの実行タイミング**：GitHubリリースが公開（published）された時に自動トリガーされる。

**主要な処理内容**：
1. ソースコードのチェックアウト
2. アーキテクチャ短縮名の決定
3. ldc-latestコンパイラのインストール
4. dub testによるユニットテスト実行
5. プラットフォーム別のビルドスクリプト実行 + ci/validate_version.dによるバージョン検証
6. ビルド成果物をリリースアセットとしてアップロード（WebFreak001/upload-asset アクション使用）
7. 依存関係バイナリのキャッシュ保存

**前後の処理との関連**：ci/build.sh（No.3）、ci/build.bat（No.4）を内部で呼び出す。ビルド後にci/validate_version.d（No.11）によるバージョン検証を実行する。ナイトリービルドワークフロー（No.8）の正式リリース版に相当する。

**影響範囲**：トリガーとなったGitHubリリースのアセットとして、各プラットフォーム向けのアーカイブファイルがアップロードされる。

## バッチ種別

CI/CDワークフロー

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（リリース公開時） |
| 実行時刻 | リリース公開時 |
| 実行曜日 | 指定なし |
| 実行日 | 指定なし |
| トリガー | GitHubリリースのpublishedイベント |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| GitHubリポジトリ | Pure-D/serve-dリポジトリにアクセス可能であること |
| GITHUB_TOKEN | シークレットにGITHUB_TOKENが設定されていること |
| GitHubリリース | リリースが公開（published）されていること |
| GitHub Actionsランナー | ubuntu-22.04、windows-latest、macos-latestが利用可能であること |

### 実行可否判定

GitHubリリースのpublishedイベントにより自動的にトリガーされる。fail-fast: falseが設定されているため、1つのマトリクスジョブが失敗しても他のジョブは継続実行される。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | リリースイベントから自動的に情報を取得 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| serve-dリポジトリ | Git | actions/checkout@v4でチェックアウト |
| GitHubリリースイベント | JSON | GITHUB_EVENT_PATHからリリース情報（タグ名など）を取得 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| serve-d_{TAG}-linux-{arch}.tar.xz | tar.xz | Linux向けXZ圧縮アーカイブ |
| serve-d_{TAG}-linux-{arch}.tar.gz | tar.gz | Linux向けGZip圧縮アーカイブ |
| serve-d_{TAG}-osx-{arch}.tar.xz | tar.xz | macOS向けXZ圧縮アーカイブ |
| serve-d_{TAG}-osx-{arch}.tar.gz | tar.gz | macOS向けGZip圧縮アーカイブ |
| serve-d_{TAG}-windows-{arch}.zip | ZIP | Windows向けZIPアーカイブ |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | serve-d_{TAG}-{OS}.{ext}（TAGはリリースタグ名、OSはplatform-arch） |
| 出力先 | トリガーとなったGitHubリリースのアセット |
| アーカイブ内容 | Linux/macOS: serve-dバイナリ、Windows: serve-d.exe + DLL |

## 処理フロー

### 処理シーケンス

```
1. マトリクス構成の決定
   └─ OS: ubuntu-22.04, windows-latest, macos-latest
   └─ ARCH: x86_64（基本）
   └─ 追加: windows x86、macOS arm64-apple-macos（クロスコンパイル）
2. ソースコードのチェックアウト
   └─ actions/checkout@v4
3. 変数の決定（varsステップ）
   └─ arch_short: アーキテクチャ短縮名
4. D言語コンパイラのインストール
   └─ dlang-community/setup-dlang@v1（ldc-latest）
5. ユニットテスト実行
   └─ dub test
6. プラットフォーム別ビルド + バージョン検証
   └─ Linux: ./ci/build.sh && rdmd ci/validate_version.d
   └─ macOS: ./ci/build.sh && rdmd ci/validate_version.d
   └─ Windows: (.\ci\build.bat) -and (rdmd ci\validate_version.d)
   └─ BUILD=release固定
7. ビルド成果物のアップロード
   └─ WebFreak001/upload-asset@master アクションでリリースアセットにアップロード
   └─ ファイル名に${TAG}と${OS}が展開される
8. 依存関係キャッシュの保存
   └─ WebFreak001/dub-upgrade@v0.1.0（store: true）
```

### フローチャート

```mermaid
flowchart TD
    A[リリース published イベント] --> B[マトリクス構成決定]
    B --> C[actions/checkout@v4]
    C --> D[arch_short 変数決定]
    D --> E[ldc-latest インストール]
    E --> F[dub test]
    F --> G{OS判定}
    G -->|ubuntu-22.04| H[./ci/build.sh && rdmd ci/validate_version.d]
    G -->|macos-latest| I[./ci/build.sh && rdmd ci/validate_version.d]
    G -->|windows-latest| J[ci\build.bat -and rdmd ci\validate_version.d]
    H --> K[upload-asset: tar.xz + tar.gz]
    I --> L[upload-asset: tar.xz + tar.gz]
    J --> M[upload-asset: zip]
    K --> N[依存関係キャッシュ保存]
    L --> N
    M --> N
    N --> O[ワークフロー終了]
```

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

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

本バッチはデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | テスト失敗 | dub testが失敗した場合 | テスト失敗の原因を調査し修正する |
| - | ビルドエラー | ci/build.shまたはci/build.batが失敗した場合 | ビルドエラーの原因を調査する |
| - | バージョン不整合 | validate_version.dがバージョン不一致を検出した場合 | リリースタグとバイナリバージョンを一致させる |
| - | アップロードエラー | リリースアセットのアップロードに失敗した場合 | GITHUB_TOKENの権限を確認する |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | - |
| リトライ対象エラー | - |

### 障害時対応

fail-fast: falseにより、1つのジョブが失敗しても他のジョブは継続実行される。バージョン検証に失敗した場合は、リリースタグを修正するか、serve-dのバージョン定義を修正して再リリースする。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | なし（各デプロイは独立したファイルアップロード） |
| コミットタイミング | - |
| ロールバック条件 | なし（リリースアセットの手動削除が必要） |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | マトリクスの組み合わせ数（5ジョブ） |
| 目標処理時間 | GitHub Actionsのタイムアウト内 |
| メモリ使用量上限 | GitHub Actionsランナーのデフォルトリソース |

## 排他制御

マトリクスの各ジョブは独立した仮想マシン上で並列実行されるため、排他制御は不要。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| ワークフローログ | 全ステップ | GitHub Actionsの標準ログ |
| テスト結果 | dub test実行時 | テスト成功/失敗の詳細 |
| ビルドログ | ビルドスクリプト実行時 | ビルド進捗・エラー情報 |
| バージョン検証結果 | validate_version.d実行時 | バージョン一致/不一致の結果 |
| アップロードログ | アセットアップロード時 | アップロード成功/失敗 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ワークフロー結果 | 失敗時 | GitHub Actions通知 |

## 備考

- nightly.yml（No.8）との主な違い:
  - トリガー: スケジュールではなくリリースpublishedイベント
  - ビルドタイプ: release-debugではなくrelease固定
  - バージョン検証: ci/validate_version.dによる検証が追加
  - デプロイ: deploy-nightlyではなくupload-assetアクション使用
  - ファイル名: 日付ではなくリリースタグ（${TAG}）がファイル名に含まれる
- macOS arm64ビルドはクロスコンパイル（cross: "1"）で行われる
- MACOSX_DEPLOYMENT_TARGET=10.12によりmacOS Sierra以降との互換性を確保
- ubuntu-22.04はglibc互換性のために選択されている
- ワークフロー名は "Upload prebuild binaries" となっている
