# バッチ設計書 4-Create Release

## 概要

本ドキュメントは、Decap CMSプロジェクトにおけるCreate Releaseワークフローのバッチ設計書である。GitHub Actionsで定義されたCI/CDパイプラインのうち、`decap-cms@`形式のタグ作成時にGitHub Releaseを自動生成する処理について記述する。

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

本バッチは、Decap CMSのメインパッケージ（decap-cms）のリリース時にGitHub Releaseを自動生成するバッチである。`decap-cms@`で始まるGitタグが作成された際に自動トリガーされ、タグ名からセマンティックバージョンを抽出してGitHub Releaseを作成する。リリースノートにはCHANGELOG.mdへのリンクが含まれる。

**業務上の目的・背景**：Decap CMSのリリース時に、GitHubユーザーがリリースページからバージョン情報と変更内容を確認できるようにするため、GitHub Releaseの自動生成が必要である。手動でのリリース作成は、リリース漏れや記載ミスのリスクがあるため、タグ作成をトリガーとした自動化により、一貫性のあるリリースノートの生成を実現する。

**バッチの実行タイミング**：`decap-cms@`で始まるGitタグが作成（create）された時にイベント駆動で自動実行される。

**主要な処理内容**：
1. リポジトリのチェックアウト
2. タグ名からセマンティックバージョン番号の抽出（refs/tags/の10文字をスキップ）
3. GitHub APIを使用したGitHub Releaseの自動作成（CHANGELOG.mdへのリンク付き）

**前後の処理との関連**：No.3（Publish Packages）の実行後にタグがpushされることで本バッチがトリガーされる場合がある。本バッチは単独で完結し、後続のバッチは存在しない。

**影響範囲**：GitHubリポジトリのReleasesページに新しいリリースが追加される。GitHubのウォッチャーやフィードを通じてリリース通知がユーザーに配信される。

## バッチ種別

CI/CD（リリース - GitHub Release生成）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動（随時） |
| 実行時刻 | 該当なし（タグ作成時） |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | Gitタグ作成（createイベント）かつ`refs/tags/decap-cms@`で始まるタグ |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Gitタグの作成 | `decap-cms@`で始まるタグがリポジトリに作成されていること |
| GITHUB_TOKENシークレット | GitHub APIへのアクセスに必要なトークンが利用可能であること |
| CHANGELOG.mdの存在 | リポジトリルートにCHANGELOG.mdが存在すること |

### 実行可否判定

createイベントがトリガーされた際に、`startsWith(github.ref, 'refs/tags/decap-cms@')`の条件でジョブの実行可否が判定される。`decap-cms@`以外のタグ（例：decap-server@1.0.0など）の作成時にはスキップされる。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| github.ref | 文字列 | Yes | - | タグのref（例：refs/tags/decap-cms@3.0.0） |
| GITHUB_TOKEN | シークレット | Yes | secrets.GITHUB_TOKEN | GitHub API認証トークン |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| GitHubリポジトリ | Git | チェックアウト対象のリポジトリ |
| Gitタグ名 | 文字列 | リリース名の元となるタグ名 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| GitHub Releases | GitHub Release | 作成されたリリースページ |
| GitHub Actionsログ | テキスト | リリース作成の実行ログ |

### 出力ファイル仕様

本バッチではファイル出力は行わない。GitHub APIを通じてリリースが作成される。

| 項目 | 内容 |
|-----|------|
| ファイル名 | 該当なし |
| 出力先 | GitHub Releases（https://github.com/{repository}/releases） |
| 文字コード | UTF-8 |
| 区切り文字 | 該当なし |

## 処理フロー

### 処理シーケンス

```
1. ワークフロートリガー
   └─ createイベントを検出
2. 実行条件チェック
   └─ github.refが'refs/tags/decap-cms@'で始まるかを判定
3. リポジトリチェックアウト
   └─ actions/checkout@v3
4. セマンティックバージョン抽出
   └─ TAG_NAME（github.ref）の先頭10文字をスキップして抽出
       例：refs/tags/decap-cms@3.0.0 → decap-cms@3.0.0（実際には${TAG_NAME:10}）
5. GitHub Release作成
   └─ actions/create-release@v1
       ├─ tag_name: github.ref
       ├─ release_name: 抽出したバージョン文字列
       ├─ body: CHANGELOG.mdへのリンク
       ├─ draft: false
       └─ prerelease: false
```

### フローチャート

```mermaid
flowchart TD
    A[createイベント発生] --> B{refs/tags/decap-cms@ で始まる?}
    B -->|いいえ| C[スキップ]
    B -->|はい| D[リポジトリチェックアウト]
    D --> E[タグ名からセマンティックバージョン抽出]
    E --> F[GitHub Release作成]
    F --> G{作成成功?}
    G -->|成功| H[ワークフロー成功]
    G -->|失敗| I[ワークフロー失敗]
    C --> J[ワークフロー終了]
    H --> J
    I --> J
```

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

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 該当なし | 該当なし | 該当なし | 該当なし |

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | GitHub API認証失敗 | GITHUB_TOKENが無効または期限切れの場合 | シークレットの設定を確認する |
| - | リリース作成失敗 | 同一タグのリリースが既に存在する場合 | 既存リリースを削除してから再実行する |
| - | チェックアウト失敗 | リポジトリへのアクセスに失敗した場合 | ネットワーク状態を確認して再実行する |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 自動リトライなし（GitHub Actions UIから手動で再実行可能） |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

バッチ（ワークフロー）失敗時は以下の手順で対応する：
1. GitHub Actionsのログでどのステップでエラーが発生したかを確認する
2. GitHub APIエラーの場合はGITHUB_TOKENの権限を確認する
3. 必要に応じてGitHub UIから手動でリリースを作成する

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし（GitHub API単一操作） |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし（リリース作成は冪等ではないため、手動削除が必要） |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1件（1リリースの作成） |
| 目標処理時間 | 1分以内 |
| メモリ使用量上限 | 最小（GitHub API呼び出しのみ） |

## 排他制御

明示的な排他制御は設定されていない。createイベントはタグ作成ごとに1回のみ発生するため、通常は重複実行の問題は発生しない。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | ジョブ開始時 | GitHub Actionsにより自動的にジョブ開始が記録される |
| バージョン抽出ログ | get_semverステップ | 抽出されたセマンティックバージョン文字列 |
| リリース作成ログ | create_releaseステップ | 作成されたリリースの情報 |
| 終了ログ | ジョブ終了時 | GitHub Actionsにより自動的にジョブ完了ステータスが記録される |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ジョブ成功/失敗 | 失敗時 | GitHubリポジトリの管理者への通知 |

## 備考

- actions/checkout@v3（v4ではなくv3）を使用している点に注意
- actions/create-release@v1はアーカイブされたアクションであり、将来的に代替アクションへの移行が推奨される
- `set-output`コマンドは非推奨であり、将来的に`$GITHUB_OUTPUT`への移行が必要になる可能性がある
- TAG_NAMEの先頭10文字スキップ（${TAG_NAME:10}）は`refs/tags/`の10文字に対応する
- リリースノートのbodyにはCHANGELOG.mdへのリンクが含まれ、スクロール絵文字（:scroll:）が付与される
- draft: false, prerelease: falseが設定されており、正式リリースとして公開される
