# バッチ設計書 20-update-stable-docs

## 概要

本ドキュメントは、Prettierプロジェクトにおける `update-stable-docs.mjs` バッチの設計仕様を定義します。このバッチは、Prettierウェブサイトの安定版ドキュメントを更新するスクリプトです。

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

このバッチは、現在のドキュメントを安定版ドキュメントディレクトリにコピーし、バージョンプレースホルダーを実際のバージョン番号に置換します。Docusaurusのバージョン管理機能と連携して、安定版ドキュメントを維持します。

**業務上の目的・背景**：Prettierウェブサイトは複数バージョンのドキュメントを提供しています。新しいバージョンがリリースされた際、最新のドキュメントを「stable」バージョンとしてコピーし、CDNリンクやnpmコマンドのバージョン番号を正しい値に更新する必要があります。このスクリプトはその作業を自動化します。

**バッチの実行タイミング**：Prettierの新バージョンリリース時、またはドキュメント更新時に実行します。CI/CDパイプラインの一部として自動実行されることもあります。

**主要な処理内容**：
1. Prettierのバージョン番号を取得（環境変数またはpackage.jsonから）
2. 現在のサイドバー設定を安定版サイドバーにコピー
3. 既存の安定版ドキュメントディレクトリを削除
4. 現在のドキュメントを安定版ディレクトリにコピー
5. 特定のファイル内のバージョンプレースホルダーを置換

**前後の処理との関連**：このバッチはウェブサイトのビルドプロセスの一部として実行されます。実行後、Docusaurusのビルドが安定版ドキュメントを含めて実行されます。

**影響範囲**：`website/versioned_docs/version-stable/`ディレクトリと`website/versioned_sidebars/version-stable-sidebars.json`が更新されます。

## バッチ種別

ドキュメント同期 / データ連携

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（リリース時） |
| 実行時刻 | N/A |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | CIパイプライン / 手動実行 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Node.js環境 | Node.js実行環境が利用可能であること |
| ドキュメントディレクトリ | docs/ディレクトリが存在すること |
| サイドバー設定 | sidebars.jsonが存在すること |

### 実行可否判定

ドキュメントディレクトリとサイドバー設定が存在する場合に実行可能です。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | コマンドライン引数は受け取りません |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| docs/ | ディレクトリ | 現在のドキュメントファイル群 |
| sidebars.json | JSON | サイドバー設定 |
| package.json | JSON | バージョン情報（環境変数がない場合） |

### 環境変数

| 変数名 | 説明 | デフォルト値 |
|-------|------|-------------|
| PRETTIER_VERSION | Prettierのバージョン番号 | package.jsonのversion |
| PULL_REQUEST | PRビルドかどうか | なし |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| website/versioned_docs/version-stable/ | ディレクトリ | 安定版ドキュメント |
| website/versioned_sidebars/version-stable-sidebars.json | JSON | 安定版サイドバー設定 |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ドキュメント出力先 | website/versioned_docs/version-stable/ |
| サイドバー出力先 | website/versioned_sidebars/version-stable-sidebars.json |
| 文字コード | UTF-8 |
| プレースホルダー置換対象 | browser.md, install.md, sharing-configurations.md |

## 処理フロー

### 処理シーケンス

```
1. バージョン取得
   └─ PRETTIER_VERSION環境変数を確認
   └─ なければpackage.jsonから取得

2. サイドバーのコピー
   └─ sidebars.jsonをversion-stable-sidebars.jsonにコピー

3. 安定版ドキュメントディレクトリの準備
   └─ 既存のversion-stable/ディレクトリを削除
   └─ 新しいディレクトリを作成

4. ドキュメントのコピー
   └─ docs/の内容をversion-stable/にコピー

5. バージョンプレースホルダーの置換
   └─ PULL_REQUEST環境変数がtrueでない場合のみ実行
   └─ browser.md, install.md, sharing-configurations.mdを処理
   └─ %PRETTIER_VERSION%を実際のバージョンに置換
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[バージョン取得]
    B --> C{PRETTIER_VERSION環境変数?}
    C -->|あり| D[環境変数のバージョンを使用]
    C -->|なし| E[package.jsonから取得]
    D --> F[サイドバーをコピー]
    E --> F
    F --> G[既存ドキュメント削除]
    G --> H[ドキュメントディレクトリ作成]
    H --> I[ドキュメントをコピー]
    I --> J{PULL_REQUEST=true?}
    J -->|はい| K[プレースホルダー置換スキップ]
    J -->|いいえ| L[プレースホルダー置換]
    L --> M[browser.md更新]
    M --> N[install.md更新]
    N --> O[sharing-configurations.md更新]
    K --> P[バッチ終了]
    O --> P
```

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

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

データベース操作はありません。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ディレクトリ読み込みエラー | docs/が存在しない | ドキュメントを作成 |
| - | ファイル読み込みエラー | sidebars.jsonが存在しない | ファイルを作成 |

### リトライ仕様

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

### 障害時対応

1. ディレクトリがない場合：必要なディレクトリ構造を作成
2. package.jsonがない場合：PRETTIER_VERSION環境変数を設定

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | N/A |
| コミットタイミング | N/A |
| ロールバック条件 | N/A |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | ドキュメントファイル数分 |
| 目標処理時間 | 数秒以内 |
| メモリ使用量上限 | 制限なし |

## 排他制御

同時実行の制限はありませんが、同時実行は推奨されません。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| なし | - | ログ出力は実装されていません |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 実行エラー | 発生時 | CIパイプラインの失敗通知 |

## 備考

- ES Modules形式（.mjs）で実装されています
- Docusaurusのバージョン管理機能と連携しています
- PULL_REQUEST環境変数がtrueの場合、プレースホルダー置換はスキップされます（一時的なバージョンを使用しないため）
- バージョンプレースホルダーは`%PRETTIER_VERSION%`形式です
- fs.cpでディレクトリを再帰的にコピーします
- fs.rmでディレクトリを再帰的に削除します（force: trueで存在しない場合もエラーにならない）
