# バッチ設計書 13-update-colorschemes.yml

## 概要

本ドキュメントは、GitHub Actions ワークフロー `update-colorschemes.yml` の設計仕様を記載したバッチ設計書です。iTerm2カラースキームを週次で更新し、自動的にプルリクエストを作成するワークフローの詳細を説明します。

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

このバッチは、iTerm2-Color-Schemesリポジトリから最新のカラースキームをダウンロードし、Ghosttyプロジェクトに取り込むための自動更新処理を実行します。外部依存関係の更新を自動化し、ユーザーに最新のカラースキームオプションを提供します。

**業務上の目的・背景**：Ghosttyターミナルエミュレータでは、ユーザーがiTerm2互換のカラースキームを使用できます。iTerm2-Color-Schemesは広く使われているカラースキーム集であり、定期的に新しいスキームが追加されます。本ワークフローは、この外部依存関係を自動的に最新状態に保ち、開発者の手動作業を削減しながら、ユーザーに最新のカラースキーム選択肢を提供します。

**バッチの実行タイミング**：毎週日曜日の0時（UTC）にスケジュール実行されます。また、workflow_dispatchによる手動実行も可能であり、緊急の更新が必要な場合に対応できます。

**主要な処理内容**：
1. iTerm2-Color-Schemesの最新リリース情報を取得
2. ghostty-themes.tgzをダウンロード
3. Cloudflare R2（deps）にテーマファイルをアップロード
4. Zigの依存関係を更新（zig fetch）
5. Zigキャッシュハッシュを更新
6. ビルドテストを実行して動作確認
7. 変更をプルリクエストとして作成

**前後の処理との関連**：本ワークフローは独立して実行されます。生成されるプルリクエストは、人間のレビュー後にマージされます。マージ後は通常のCI/CDパイプライン（test.yml等）が実行されます。

**影響範囲**：build.zig.zon、build.zig.zon.nix、build.zig.zon.txt、build.zig.zon.json、flatpak/zig-packages.jsonの各ファイルが更新されます。また、Cloudflare R2のghostty-depsバケットに新しいテーマファイルがアップロードされます。

## バッチ種別

データ連携 / 依存関係更新

## 実行スケジュール

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

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| リポジトリ | ghostty-org/ghostty リポジトリでのみ実行 |
| 外部依存 | iTerm2-Color-Schemesに新しいリリースが存在すること |
| 権限 | contents: write, pull-requests: write |

### 実行可否判定

`github.repository == 'ghostty-org/ghostty'` の条件で、公式リポジトリでのみ実行されます。フォークでは実行されません。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | 入力パラメータなし |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| GitHub API | JSON | iTerm2-Color-Schemesの最新リリース情報 |
| ghostty-themes.tgz | tarball | Ghostty用カラースキームファイル |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| ghostty-deps バケット | R2 | テーマファイルのアップロード先 |
| Pull Request | GitHub PR | 更新内容を含むプルリクエスト |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | ghostty-themes-${TAG_NAME}.tgz |
| 出力先 | ghostty-deps バケット |
| 更新ファイル | build.zig.zon, build.zig.zon.nix, build.zig.zon.txt, build.zig.zon.json, flatpak/zig-packages.json |

## 処理フロー

### 処理シーケンス

```
1. コードチェックアウト
   └─ fetch-depth: 0 で全履歴を取得
2. キャッシュ・Nix環境セットアップ
   └─ /nix, /zigディレクトリをキャッシュ
3. カラースキームダウンロード
   └─ gh APIで最新リリースを取得しダウンロード
4. R2アップロード
   └─ ghostty-depsバケットにアップロード
5. Zig依存関係更新
   └─ zig fetch --save="iterm2_themes"
6. Zigキャッシュハッシュ更新
   └─ check-zig-cache.sh --update
7. ビルドテスト
   └─ nix build .#ghostty
8. プルリクエスト作成
   └─ peter-evans/create-pull-request
```

### フローチャート

```mermaid
flowchart TD
    A[ワークフロー開始] --> B[コードチェックアウト]
    B --> C[キャッシュセットアップ]
    C --> D[Nixセットアップ]
    D --> E[最新リリース情報取得]
    E --> F[テーマファイルダウンロード]
    F --> G[R2にアップロード]
    G --> H[zig fetch実行]
    H --> I{build.zig.zon変更?}
    I -->|なし| J[スキップ]
    I -->|あり| K[キャッシュハッシュ更新]
    K --> L[ビルドテスト]
    L --> M[PR作成]
    M --> N[ワークフロー終了]
    J --> N
```

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

本ワークフローではデータベース操作は行いません。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ダウンロードエラー | iTerm2-Color-Schemesへのアクセス失敗 | 時間をおいて再実行 |
| - | R2アップロードエラー | Cloudflare R2への接続失敗 | 認証情報を確認 |
| - | ビルドエラー | テーマ更新によるビルド失敗 | 手動で原因を調査 |
| - | キャッシュエラー | Zigキャッシュハッシュ不整合 | ハッシュを手動更新 |

### リトライ仕様

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

### 障害時対応

1. GitHub Actions UIでエラーログを確認
2. iTerm2-Color-Schemesのリリース状態を確認
3. R2認証情報（シークレット）を確認
4. ビルドエラーの場合は依存関係の互換性を調査

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 全処理 |
| コミットタイミング | PR作成時 |
| ロールバック条件 | ビルドテスト失敗時はPR作成されない |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1回/週 |
| 目標処理時間 | 15分以内 |
| メモリ使用量上限 | 指定なし |

## 排他制御

排他制御は設定されていません。週次実行のため、同時実行の可能性は低いです。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | ワークフロー開始時 | GitHub Actions標準ログ |
| ダウンロードログ | テーマダウンロード時 | タグ名、ファイル名 |
| 更新ログ | ファイル更新時 | 変更されたファイル一覧 |
| 終了ログ | ワークフロー終了時 | PR作成結果 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ワークフロー失敗 | 1回 | GitHub通知 |
| ビルド失敗 | 1回 | GitHub通知 |

## 備考

- peter-evans/create-pull-request@v8.1.0 を使用してPR作成
- PRタイトル: "Update iTerm2 colorschemes"
- PRブランチ: iterm2_colors_action
- コミットメッセージ: "deps: Update iTerm2 color schemes"
- PRラベル: dependencies
- Cachix（ghostty）を使用してNixビルドをキャッシュ
- ryand56/r2-upload-action@v1.4 を使用してR2にアップロード
