# バッチ設計書 8-nightly.yml

## 概要

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

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

本バッチは、毎日スケジュール実行されるGitHub Actionsワークフローであり、Linux/Windows/macOS向けのserve-dバイナリをビルドし、GitHubリリースのナイトリーアセットとしてデプロイする。

**業務上の目的・背景**：serve-dの最新のmasterブランチのコードを毎日自動ビルドし、ナイトリーリリースとして配布することで、ユーザーが最新の開発版バイナリに容易にアクセスできるようにする。各プラットフォーム（Linux x86_64、Windows x86_64/x86、macOS x86_64/arm64）向けのバイナリを自動生成し、既存のナイトリーリリース（ID: 20717582）のアセットとして日付入りファイル名でアップロードする。

**バッチの実行タイミング**：毎日02:00 UTC（cron: '0 2 * * *'）にスケジュール実行される。また、workflow_dispatchにより手動トリガーも可能。

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

**前後の処理との関連**：ci/build.sh（No.3）およびci/build.bat（No.4）を内部で呼び出す。リリース用の類似ワークフローとしてreleases.yml（No.9）がある。

**影響範囲**：GitHubリリース（ID: 20717582）のナイトリーアセットが更新される。各プラットフォーム向けのtar.xz、tar.gz、ZIPファイルがアップロードされる。

## バッチ種別

CI/CDワークフロー

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 日次 |
| 実行時刻 | 02:00 UTC |
| 実行曜日 | 毎日 |
| 実行日 | 毎日 |
| トリガー | cron（スケジュール）/ workflow_dispatch（手動） |

## 実行条件

### 前提条件

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

### 実行可否判定

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | ワークフローの入力パラメータはない |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| serve-dリポジトリ | Git | actions/checkout@v4でチェックアウト |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| serve-d_linux-nightly-{arch}-{date}.tar.xz | tar.xz | Linux向けXZ圧縮アーカイブ |
| serve-d_linux-nightly-{arch}-{date}.tar.gz | tar.gz | Linux向けGZip圧縮アーカイブ |
| serve-d_osx-nightly-{arch}-{date}.tar.xz | tar.xz | macOS向けXZ圧縮アーカイブ |
| serve-d_osx-nightly-{arch}-{date}.tar.gz | tar.gz | macOS向けGZip圧縮アーカイブ |
| serve-d_windows-nightly-{arch}-{date}.zip | ZIP | Windows向けZIPアーカイブ |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | serve-d_{platform}-nightly-{arch}-{date}.{ext} |
| 出力先 | GitHubリリースアセット（リリースID: 20717582） |
| アーカイブ内容 | 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: アーキテクチャ短縮名（matrix.arch_shortまたはmatrix.arch）
   └─ build: ビルドタイプ（matrix.buildまたはrelease-debug）
4. D言語コンパイラのインストール
   └─ dlang-community/setup-dlang@v1（ldc-latest）
5. ユニットテスト実行
   └─ dub test
6. プラットフォーム別ビルド
   └─ Linux: ./ci/build.sh（ARCH, ARCH_SHORT, BUILD環境変数）
   └─ macOS: ./ci/build.sh（+ MACOSX_DEPLOYMENT_TARGET=10.12, CROSS環境変数）
   └─ Windows: .\ci\build.bat（BUILD, ARCH, ARCH_SHORT, CROSS環境変数）
7. ビルド成果物のデプロイ
   └─ WebFreak001/deploy-nightly@master アクションでリリースアセットにアップロード
   └─ Linux: tar.xz + tar.gz
   └─ macOS: tar.xz + tar.gz
   └─ Windows: zip
8. 依存関係キャッシュの保存
   └─ WebFreak001/dub-upgrade@v0.1.0（store: true）
```

### フローチャート

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

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | テスト失敗 | dub testが失敗した場合 | テスト失敗の原因を調査し修正する |
| - | ビルドエラー | ci/build.shまたはci/build.batが失敗した場合 | ビルドエラーの原因を調査する |
| - | デプロイエラー | リリースアセットのアップロードに失敗した場合 | GITHUB_TOKENの権限を確認する |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（GitHub Actionsのデフォルト動作に依存） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

### 障害時対応

fail-fast: falseにより、1つのジョブが失敗しても他のジョブは継続実行される。失敗したジョブのログをGitHub Actions上で確認し、原因を調査する。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | なし（各デプロイは独立したファイルアップロード） |
| コミットタイミング | - |
| ロールバック条件 | なし（アセットは上書き方式） |

## パフォーマンス要件

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

## 排他制御

マトリクスの各ジョブは独立した仮想マシン上で並列実行されるため、排他制御は不要。ナイトリーリリースアセットのアップロードはファイル名が異なるため競合しない。

## ログ出力

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

## 監視・アラート

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

## 備考

- ナイトリーリリースのID（20717582）はハードコードされている
- ubuntu-22.04は比較的古いLinux環境であり、glibc互換性のために選択されている
- macOS arm64ビルドはクロスコンパイル（cross: "1"）で行われ、ビルドタイプはreleaseとなる
- ナイトリービルドのデフォルトビルドタイプはrelease-debug（matrixにbuild指定がない場合）
- MACOSX_DEPLOYMENT_TARGET=10.12により、macOS 10.12（Sierra）以降との互換性を確保
- deploy-nightlyアクションにより、ファイル名の `$$` 部分が日付に置換される
