# バッチ設計書 3-release.js

## 概要

本ドキュメントは、Vue.jsプロジェクトのリリースプロセス自動化スクリプト `scripts/release.js` の設計仕様を定義するバッチ設計書である。

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

本バッチは、Vue.jsフレームワークのリリースプロセスを自動化するスクリプトである。バージョン更新、テスト実行、プロダクションビルド、npm公開、Gitタグ作成・プッシュの一連のリリース工程を統合的に管理する。

**業務上の目的・背景**：Vue.jsのリリースは多数のパッケージのバージョン同期、相互依存関係の更新、テスト実行、ビルド、npmへのパブリッシュ、Gitタグの作成など複雑な手順を必要とする。本バッチはこれらの手順を自動化し、人為的なミスを防ぎつつ一貫したリリースプロセスを実現する。ドライランモードにより、実際の公開前にリリース手順を検証することも可能である。

**バッチの実行タイミング**：新バージョンのリリース時に手動で実行される。通常はメンテナーがローカル環境で実行し、npmパブリッシュはGitHub Actions（release.yml）に委任する。`--publish` オプション指定時は直接npmにパブリッシュする。

**主要な処理内容**：
1. リモートリポジトリとの同期確認
2. リリースバージョンの選択（対話的プロンプトまたはコマンドライン引数）
3. CI実行結果の確認とテスト実行判定
4. 全パッケージのバージョン更新と相互依存関係の同期
5. Changelogの生成
6. pnpm-lock.yamlの更新
7. 変更のGitコミット
8. パッケージのビルドとnpmパブリッシュ（--publish指定時）
9. Gitタグの作成とリモートへのプッシュ

**前後の処理との関連**：本バッチは `scripts/utils.js` の `exec` 関数を使用する。`--publish` 指定時は内部で `pnpm run build --withTypes` を呼び出し（`scripts/build.js` に相当）、その後各パッケージを `pnpm publish` する。Git操作完了後は GitHub Actions の `release.yml` ワークフローがトリガーされる。

**影響範囲**：全パッケージの `package.json`（バージョン番号と依存関係）が更新される。`CHANGELOG.md` が再生成される。`pnpm-lock.yaml` が更新される。Gitリポジトリにリリースコミットとタグが作成される。npmレジストリにパッケージが公開される（--publish指定時）。

## バッチ種別

リリース処理

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（リリース時） |
| 実行時刻 | - |
| 実行曜日 | - |
| 実行日 | - |
| トリガー | 手動実行（メンテナーによる起動） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Node.js実行環境 | Node.jsがインストールされていること |
| pnpm依存関係 | `pnpm install` により依存パッケージがインストール済みであること |
| Gitリポジトリ | Gitリポジトリ内で実行すること。リモート（origin）が設定されていること |
| リモート同期 | ローカルHEADがリモートブランチと同期していること（確認プロンプトあり） |
| npm認証 | `--publish` 指定時はnpmレジストリへの認証が完了していること |
| GitHub API | CI結果確認のためGitHub APIへのアクセスが可能であること |

### 実行可否判定

1. ローカルHEADがリモートと同期しているか確認（GitHub APIで検証、不一致の場合は確認プロンプト）
2. 指定されたバージョンがsemverとして有効であるか検証
3. CI（GitHub Actions）の実行結果を確認し、テストをスキップするか判定

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| [positionals] | string | No | - | リリースバージョン（例: "3.4.0"）またはリリースタイプ（例: "patch"） |
| --preid | string | No | 現行バージョンのプレリリースID | プレリリース識別子（例: "alpha", "beta"） |
| --dry | boolean | No | false | ドライランモード（実際の操作を行わない） |
| --tag | string | No | 自動判定 | npmパブリッシュ時のディストリビューションタグ |
| --skipBuild | boolean | No | false | ビルドをスキップ |
| --skipTests | boolean | No | false | テストをスキップ |
| --skipGit | boolean | No | false | Gitコミット・タグ・プッシュをスキップ |
| --skipPrompts | boolean | No | false | 対話的プロンプトをスキップ（CI向け） |
| --publish | boolean | No | false | ビルドとnpmパブリッシュを直接実行 |
| --publishOnly | boolean | No | false | パブリッシュのみ実行（バージョン更新・テスト等をスキップ） |
| --registry | string | No | npmデフォルト | npmレジストリURL |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| package.json（ルート） | JSON | 現行バージョンの参照元 |
| packages/ ディレクトリ | ファイルシステム | リリース対象パッケージ一覧 |
| packages/{pkg}/package.json | JSON | 各パッケージのバージョンと依存関係 |
| GitHub API | REST API | CI実行結果とリモートコミット情報 |
| .git/ | Git | ローカルのコミットハッシュとブランチ情報 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| package.json（ルート・全パッケージ） | JSON | バージョン番号が更新される |
| CHANGELOG.md | Markdown | 変更履歴が再生成される |
| pnpm-lock.yaml | YAML | ロックファイルが更新される |
| Gitリポジトリ | Git | リリースコミットとバージョンタグ |
| npmレジストリ | npm | パッケージが公開される（--publish指定時） |
| 標準出力 | テキスト | リリース進捗メッセージ |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | 各パッケージの `package.json` |
| 出力先 | `packages/{pkg}/` |
| 文字コード | UTF-8 |
| 区切り文字 | - |

## 処理フロー

### 処理シーケンス

```
1. リモート同期確認
   └─ GitHub APIでリモートの最新コミットとローカルHEADを比較
2. リリースバージョンの決定
   └─ 位置引数があればそれを使用、なければ対話的プロンプトでバージョンタイプを選択
   └─ semver検証を実施
3. テスト実行判定
   └─ GitHub APIでCIの実行結果を確認
   └─ CIが成功していればローカルテストのスキップを提案
   └─ テスト実行が必要な場合は `pnpm run test --run` を実行
4. バージョン更新
   └─ ルートpackage.jsonと全パッケージのpackage.jsonのバージョンを更新
   └─ 相互依存関係（dependencies, peerDependencies）も同時に更新
5. Changelog生成
   └─ `pnpm run changelog` を実行
6. ロックファイル更新
   └─ `pnpm install --prefer-offline` を実行
7. Gitコミット（--skipGit未指定時）
   └─ `git add -A` → `git commit -m "release: v{version}"` を実行
8. パッケージビルドとnpmパブリッシュ（--publish指定時）
   └─ `pnpm run build --withTypes` を実行
   └─ 各パッケージを `pnpm publish` で公開（リリースタグ自動判定）
9. Gitタグとプッシュ（--skipGit未指定時）
   └─ `git tag v{version}` → `git push origin refs/tags/v{version}` → `git push` を実行
10. 完了メッセージ表示
    └─ スキップされたパッケージの一覧を表示
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B{publishOnly?}
    B -->|Yes| C[publishOnly処理]
    B -->|No| D[リモート同期確認]
    D --> E{同期OK?}
    E -->|No| F[終了]
    E -->|Yes| G[バージョン決定]
    G --> H{semver有効?}
    H -->|No| I[エラー終了]
    H -->|Yes| J[テスト実行判定]
    J --> K[バージョン更新]
    K --> L[Changelog生成]
    L --> M[ロックファイル更新]
    M --> N{skipGit?}
    N -->|No| O[Gitコミット]
    N -->|Yes| P{publish?}
    O --> P
    P -->|Yes| Q[ビルド実行]
    Q --> R[npmパブリッシュ]
    R --> S{skipGit?}
    P -->|No| S
    S -->|No| T[Gitタグ作成・プッシュ]
    S -->|Yes| U[完了]
    T --> U
    C --> U
```

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

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

本バッチはデータベース操作を行わない。npmレジストリへのパッケージ公開はHTTP APIを介して行われる。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | バージョン検証エラー | 指定バージョンがsemverとして無効 | 正しいバージョン文字列を指定 |
| - | リモート同期エラー | GitHub APIへのアクセス失敗 | ネットワーク接続を確認して再実行 |
| - | テスト失敗 | pnpm run testがエラー終了 | テストを修正して再実行 |
| - | npmパブリッシュエラー | パッケージが既にパブリッシュ済み | "previously published"の場合はスキップされる |
| - | CI未完了エラー（skipPrompts時） | skipPrompts指定時にCIが未完了 | CIの完了を待ってから再実行 |

### リトライ仕様

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

### 障害時対応

リリース処理が途中で失敗した場合、バージョン更新済み（`versionUpdated === true`）であれば、catchブロックで `updateVersions(currentVersion)` が呼び出され、全パッケージのバージョンが元の値にロールバックされる。Git操作が完了済みの場合は、手動でタグ削除やコミットリバートが必要になる場合がある。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | リリースプロセス全体 |
| コミットタイミング | Gitコミット時、npmパブリッシュ時 |
| ロールバック条件 | エラー発生時にバージョン番号を自動ロールバック。Git操作・npmパブリッシュは手動ロールバックが必要 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 全パッケージ（約15〜20パッケージ） |
| 目標処理時間 | テスト・ビルドを含めて数分〜十数分 |
| メモリ使用量上限 | 明示的な制限なし |

## 排他制御

リリースプロセスは同時に1つのみ実行されることを前提とする。複数のメンテナーが同時にリリースを実行した場合、Gitのpushやnpmパブリッシュで競合が発生する可能性がある。リモート同期確認がその緩和策として機能する。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 進捗ログ | 各ステップ開始時 | シアン色のステップメッセージ（step関数） |
| 成功ログ | パッケージパブリッシュ成功時 | 緑色の成功メッセージ |
| スキップログ | パブリッシュ済みパッケージ検出時 | 赤色のスキップメッセージ |
| ドライランログ | ドライランモード時 | 青色の`[dryrun]`プレフィックス付きコマンド表示 |
| 同期確認ログ | リモート同期確認成功時 | 緑色のチェックマーク付きメッセージ |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| リリース失敗 | 1件以上 | プロセス終了コード（exit(1)）により呼び出し元が検知 |
| スキップパッケージ | 1件以上 | 標準出力に黄色で表示 |

## 備考

- ドライランモード（`--dry`）では実際のGit操作やnpmパブリッシュは行われず、コマンドのログ出力のみが行われる
- `--publishOnly` モードは既にバージョン更新済みの状態からパブリッシュのみを再実行するためのモード
- プレリリースバージョン（alpha, beta, rc）の場合、npmの`--tag`オプションが自動的に設定される
- リリースコミットメッセージは `release: v{version}` 形式で固定
- privateパッケージ（`package.json` の `private: true`）はリリース対象から除外される
- CI結果の確認は `https://api.github.com/repos/vuejs/core/actions/runs` APIを使用
- `--no-git-checks` はドライラン時、skipGit時、またはCI環境で自動的に追加される
- CI環境かつデフォルトレジストリの場合、`--provenance` フラグが追加される
