# バッチ設計書 3-Publish Packages

## 概要

本ドキュメントは、Decap CMSプロジェクトにおけるPublish Packagesワークフローのバッチ設計書である。GitHub Actionsで定義されたCI/CDパイプラインのうち、タグpush時に全パッケージをビルド・テストし、Lerna経由でnpmレジストリに公開する処理について記述する。

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

本バッチは、Decap CMSの各パッケージをnpmレジストリに公開するためのリリースパイプラインバッチである。`decap-*@*`形式のタグがpushされた際に自動トリガーされ、全パッケージのビルド・テストを実施した後、Lernaのfrom-packageモードでnpmレジストリへの公開を行う。

**業務上の目的・背景**：Decap CMSはモノレポ構成で複数のnpmパッケージを管理しており、リリース時にはこれらのパッケージを一括してnpmレジストリに公開する必要がある。手動でのパッケージ公開は、公開漏れやバージョン不整合のリスクがあるため、タグpushをトリガーとした自動化により、安全かつ確実なパッケージ公開を実現する。OIDCトラステッドパブリッシャーを使用することで、npm認証トークンの管理リスクも軽減している。

**バッチの実行タイミング**：`decap-*@*`形式のGitタグがpushされた時にイベント駆動で自動実行される。

**主要な処理内容**：
1. リポジトリのフルチェックアウト（fetch-depth: 0でLernaの変更検出に対応）
2. Node.js 24のセットアップとnpmレジストリURLの設定
3. npm ciによる依存関係のインストール
4. npm run buildによる全パッケージのビルド
5. npm run test:ciによるテスト実行（品質ゲート）
6. デバッグ情報の出力（バージョン、npm設定、Git状態、パッケージ情報）
7. Lerna publishによるnpmレジストリへのパッケージ公開

**前後の処理との関連**：本バッチ実行前に、Gitタグの作成とpushが必要である。No.7（build）のスクリプトを内部で使用する。公開後にNo.4（Create Release）が別途トリガーされる場合がある（decap-cms@タグの場合）。

**影響範囲**：npmレジストリ上の全Decap CMSパッケージのバージョンが更新される。公開されたパッケージは全てのDecap CMSユーザーがnpm installで取得可能になる。

## バッチ種別

CI/CD（リリース - パッケージ公開）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動（随時） |
| 実行時刻 | 該当なし（タグpush時） |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | `decap-*@*`形式のGitタグpush |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Gitタグの作成 | `decap-*@*`形式のタグがリポジトリにpushされていること |
| production環境の承認 | GitHub環境（production）の保護ルールによる承認が完了していること |
| OIDCトラステッドパブリッシャー設定 | npmレジストリでOIDCトラステッドパブリッシャーが設定済みであること |
| パッケージバージョンの更新 | lerna.jsonおよび各パッケージのpackage.jsonのバージョンが更新済みであること |

### 実行可否判定

GitタグがpushされたときにGitHub Actionsが自動的にトリガーする。タグ名が`decap-*@*`パターンにマッチする場合にのみワークフローが実行される。production環境が設定されている場合、デプロイメント保護ルールによる承認が必要になる場合がある。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| Gitタグ名 | 文字列 | Yes | - | `decap-*@*`形式のタグ名（例：decap-cms@3.0.0） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| GitHubリポジトリ（ソースコード） | Git | fetch-depth: 0でフルヒストリをチェックアウト |
| lerna.json | JSON | Lernaのバージョニング・公開設定 |
| 各パッケージのpackage.json | JSON | 各パッケージのバージョン情報と依存関係 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| npmレジストリ | npmパッケージ | 公開されたパッケージのtarball |
| GitHub Actionsログ | テキスト | ビルド・テスト・公開の実行ログ |

### 出力ファイル仕様

本バッチではローカルファイル出力は行わない。npmレジストリへのパッケージ公開が主要な出力である。

| 項目 | 内容 |
|-----|------|
| ファイル名 | 該当なし（npmレジストリへ公開） |
| 出力先 | https://registry.npmjs.org |
| 文字コード | 該当なし |
| 区切り文字 | 該当なし |

## 処理フロー

### 処理シーケンス

```
1. ワークフロートリガー
   └─ decap-*@*形式のタグpushを検出
2. リポジトリチェックアウト
   └─ actions/checkout@v4（fetch-depth: 0でフルヒストリ取得）
3. Node.jsセットアップ
   └─ actions/setup-node@v4（Node.js 24、registry-url: https://registry.npmjs.org）
4. 依存関係インストール
   └─ npm ci
5. パッケージビルド
   └─ npm run build
       ├─ npm run build:esm（ESMビルド）
       └─ nx run-many -t build（UMDビルド）
6. テスト実行（品質ゲート）
   └─ npm run test:ci
       ├─ lint-quiet
       ├─ type-check
       └─ test:unit
7. デバッグ情報出力
   └─ Node/npm バージョン、npm設定、環境変数、Git状態、パッケージ情報
8. npm公開
   └─ npm run lerna:publish -- --loglevel silly
       └─ lerna publish from-package --yes --no-private
```

### フローチャート

```mermaid
flowchart TD
    A[タグpush: decap-*@*] --> B[production環境チェック]
    B --> C[リポジトリチェックアウト: fetch-depth=0]
    C --> D[Node.js 24セットアップ + npmレジストリ設定]
    D --> E[npm ci: 依存関係インストール]
    E --> F[npm run build: 全パッケージビルド]
    F --> G[npm run test:ci: テスト実行]
    G --> H{テスト成功?}
    H -->|失敗| I[ワークフロー失敗]
    H -->|成功| J[デバッグ情報出力]
    J --> K[lerna publish from-package]
    K --> L{公開成功?}
    L -->|成功| M[ワークフロー成功]
    L -->|失敗| I
```

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

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

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

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

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ビルド失敗 | npm run buildが失敗した場合 | ビルドエラーのログを確認し、ソースコードを修正する |
| - | テスト失敗 | npm run test:ciが失敗した場合 | テストエラーを修正し、新しいタグをpushする |
| - | npm公開失敗 | lerna publishが失敗した場合 | npmレジストリの設定・OIDC設定を確認する |
| - | OIDC認証失敗 | OIDCトラステッドパブリッシャーの認証が失敗した場合 | npmでのOIDC設定を確認する |
| - | バージョン重複 | 既に同じバージョンがnpmに公開済みの場合 | バージョンを更新して新しいタグを作成する |

### リトライ仕様

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

### 障害時対応

バッチ（ワークフロー）失敗時は以下の手順で対応する：
1. GitHub Actionsのログでどのステップでエラーが発生したかを確認する
2. ビルド・テスト失敗の場合はソースコードを修正し、新しいタグを作成してpushする
3. npm公開失敗の場合はOIDC設定やnpmレジストリの状態を確認する
4. 部分的に公開された場合はscripts/revert_publish.sh（No.24）でリリースを巻き戻す
5. デバッグステップの出力を活用して問題の特定を行う

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | パッケージ単位（Lernaが各パッケージを個別に公開） |
| コミットタイミング | 該当なし（npmレジストリへの公開は即時反映） |
| ロールバック条件 | 部分的な公開失敗時にはscripts/revert_publish.shで巻き戻し可能 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 全パッケージ（約30パッケージ）のビルド・テスト・公開 |
| 目標処理時間 | 明示的な上限なし（通常20-40分程度） |
| メモリ使用量上限 | 明示的な上限なし（GitHub Actionsランナーのデフォルトメモリ） |

## 排他制御

明示的なconcurrency設定はないが、production環境のデプロイメント保護ルールにより、同時実行は制限される場合がある。Lernaのfrom-packageモードでは、パッケージのバージョンがnpmレジストリと比較されるため、同一バージョンの重複公開は防止される。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | ジョブ開始時 | GitHub Actionsにより自動的にジョブ開始が記録される |
| ビルドログ | ビルド実行中 | Webpack/Nxのビルド出力 |
| テスト結果ログ | テスト実行後 | lint・型チェック・テストの結果 |
| デバッグログ | デバッグステップ | Node/npmバージョン、npm設定、環境変数、Git状態、Lernaパッケージ一覧 |
| 公開ログ | lerna publish実行中 | --loglevel sillyによる詳細な公開ログ |
| 終了ログ | ジョブ終了時 | GitHub Actionsにより自動的にジョブ完了ステータスが記録される |

## 監視・アラート

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

## 備考

- OIDCトラステッドパブリッシャーを使用しているため、NODE_AUTH_TOKENの明示的な設定は不要である
- permissions設定でcontents: readとid-token: writeが設定されており、OIDCに必要な最小権限が付与されている
- デバッグステップでnpm設定やGit状態が出力されるため、問題発生時のトラブルシュートが容易である
- lerna.jsonでindependentバージョニングが設定されており、各パッケージが独立してバージョン管理される
- --loglevel sillyオプションにより、Lernaの公開処理の詳細ログが出力される
- --no-privateオプションにより、private: trueのパッケージは公開対象から除外される
