# バッチ設計書 10-doom upgrade

## 概要

本ドキュメントは、Doom本体とパッケージを最新版に更新するCLIコマンド`doom upgrade`の設計仕様を定義するものである。

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

`doom upgrade`は、Doom Emacsのコアファイルとインストール済みパッケージを最新バージョンに更新するためのコマンドである。内部的には`git pull --rebase`でDoom本体を更新し、その後`doom sync -u`でパッケージを更新する。

**業務上の目的・背景**：Doom Emacsは活発に開発されており、バグ修正、新機能、パフォーマンス改善が頻繁にリリースされる。`doom upgrade`は、ユーザーがDoom本体とパッケージを安全かつ簡単に最新状態に保てるようにする。ローカルの変更を検出して警告し、更新内容の差分をブラウザで確認できるなど、安全性にも配慮している。

**バッチの実行タイミング**：以下の場合に実行が推奨される：
- Doomの新バージョンがリリースされた時
- バグ修正や新機能を取得したい時
- 定期的なメンテナンスとして

**主要な処理内容**：
1. ローカルの変更有無を確認（dirty working tree）
2. upstreamからの更新をフェッチ
3. 現在のリビジョンと新しいリビジョンの比較
4. 更新内容の差分URLを提供
5. ユーザー確認後、git reset --hardで更新
6. CLIライブラリのリロード
7. doom sync -u でパッケージを更新

**前後の処理との関連**：内部で`doom sync -u`を呼び出す。完了後は必要に応じてEmacsを再起動。

**影響範囲**：Doom Emacsコアファイル、全インストール済みパッケージ、プロファイルデータ。

## バッチ種別

アップグレード / バージョン管理

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（新バージョンリリース時） |
| 実行時刻 | ユーザー任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Git クローン済み | $EMACSDIR が Git リポジトリであること |
| ネットワーク接続 | upstream からのフェッチに必要 |
| クリーンな作業ツリー | ローカル変更がないこと（--force で無視可能） |

### 実行可否判定

1. Doomの.gitディレクトリが存在すること
2. 現在のブランチが特定可能であること
3. ネットワーク経由でupstreamにアクセス可能であること

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| --aot | フラグ | No | false | 事前ネイティブコンパイルを有効化 |
| -p, --packages | フラグ | No | false | パッケージのみを更新（Doom本体は更新しない） |
| -j, --jobs | 数値 | No | 最大CPU数 | ネイティブコンパイルのCPU数 |
| -B | フラグ | No | false | ホスト名/Emacsバージョン変更時もリビルドしない |
| --force (-!) | フラグ | No | false | ローカル変更を破棄して更新（グローバルオプション） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| doom-upgrade-url | URL | Doom Emacs の Git リポジトリURL |
| .git/ | Git | ローカルリポジトリの状態 |
| origin/* | Git | upstreamのブランチ状態 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | テキスト | 更新進捗、差分情報、ステータス |
| $EMACSDIR/ | ファイル群 | 更新されたDoomコアファイル |
| straight/build/ | ディレクトリ | 更新されたパッケージビルド |

### 出力ファイル仕様

本コマンドは既存ファイルを更新するため、新規ファイル出力仕様は該当しない。

## 処理フロー

### 処理シーケンス

```
1. Doom本体の更新（-p なし）
   └─ 現在のブランチを特定（git name-rev）
   └─ 作業ツリーのdirty状態を確認
   └─ dirty且つforce?でない場合はエラー
   └─ 既存の_upgradeリモート/ブランチをクリーンアップ

2. Upstreamからのフェッチ
   └─ _upgradeリモートを追加
   └─ git fetch --force --tags でフェッチ
   └─ 現在と新しいリビジョンを比較

3. 更新確認
   └─ 既に最新の場合は終了
   └─ 差分URLをGitHubで提供
   └─ ブラウザで差分を確認するか問う
   └─ 更新を続行するか問う

4. Doom本体の更新実行
   └─ git reset --hard target-remote
   └─ リビジョンを確認

5. パッケージ更新（-p あり、または本体更新後）
   └─ straight のレシピ変更を確認
   └─ 変更がある場合、straight.el を削除
   └─ doom sync -u を呼び出し

6. クリーンアップ
   └─ _upgradeリモート/ブランチを削除
   └─ 成功メッセージ表示
```

### フローチャート

```mermaid
flowchart TD
    A[doom upgrade 開始] --> B{-p オプション?}
    B -->|Yes| C[パッケージのみ更新]
    B -->|No| D[ブランチ特定]
    D --> E{.git存在?}
    E -->|No| F[エラー: Gitリポジトリではない]
    E -->|Yes| G{作業ツリーdirty?}
    G -->|Yes| H{--force?}
    H -->|No| I[エラー: ローカル変更あり]
    H -->|Yes| J[ローカル変更を破棄]
    G -->|No| K[既存リモート/ブランチ削除]
    J --> K
    K --> L[_upgradeリモート追加]
    L --> M[git fetch]
    M --> N{リビジョン比較}
    N -->|同じ| O[既に最新]
    N -->|異なる| P[差分URL表示]
    P --> Q{ブラウザで確認?}
    Q -->|Yes| R[ブラウザを開く]
    Q -->|No| S{更新続行?}
    R --> S
    S -->|No| T[中止]
    S -->|Yes| U[git reset --hard]
    U --> V[CLIリロード]
    V --> C
    C --> W[straightレシピ確認]
    W --> X{レシピ変更?}
    X -->|Yes| Y[straight.el削除]
    X -->|No| Z[doom sync -u]
    Y --> Z
    Z --> AA[クリーンアップ]
    O --> AA
    AA --> AB[終了]
```

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

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

本コマンドはデータベースを使用しない。

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| N/A | N/A | N/A | データベース操作なし |

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

データベース操作は行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 非ゼロ | Git未発見 | .gitディレクトリがない | Doomを正しくクローン |
| 非ゼロ | ブランチ不明 | デタッチHEAD状態 | ブランチをチェックアウト |
| user-error | Dirty作業ツリー | ローカル変更あり | stash/リセット、または--force |
| 非ゼロ | フェッチ失敗 | ネットワーク問題 | ネットワーク接続確認 |
| 非ゼロ | リセット失敗 | Git操作失敗 | 手動でgit操作 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（手動再実行） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

### 障害時対応

1. `--force`オプションでローカル変更を破棄して再試行
2. 手動で`git stash`後に再実行
3. 手動で`git pull --rebase`を実行

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | Git操作は一連の流れで実行 |
| コミットタイミング | git reset完了時 |
| ロールバック条件 | 失敗時はクリーンアップのみ（元の状態に戻らない） |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1回/アップグレード |
| 目標処理時間 | 数分〜十数分（ネットワーク・パッケージ数依存） |
| メモリ使用量上限 | Emacsプロセス + Git + コンパイル処理分 |

## 排他制御

- 同時に複数の`doom upgrade`を実行しないこと
- アップグレード中は他のDoomコマンドを実行しないこと

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | コマンド開始時 | "Preparing to upgrade Doom Emacs and its packages..." |
| 情報ログ | 新バージョン検出時 | 旧/新リビジョン、差分URL |
| 警告ログ | dirty検出時 | "You have local modifications in Doom's source..." |
| 進捗ログ | 更新中 | "Upgrading Doom Emacs...", "Reloading Doom Emacs" |
| 成功ログ | 完了時 | "Finished upgrading Doom Emacs", "Doom is already up-to-date!" |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| N/A | N/A | 監視対象外（手動実行コマンド） |

## 備考

- `doom-upgrade-url`はデフォルトで "https://github.com/doomemacs/doomemacs"
- `doom-upgrade-remote`は "_upgrade" という名前の一時的なリモート
- straightのレシピが変更された場合、straight.elを削除して再インストール
- 更新後、CLIライブラリがリロードされて`doom upgrade -p`が実行される
- `exit!`マクロで新しいDoomコマンドを実行（プロセス再起動）
- 差分URLはGitHubの比較ページ（/compare/OLD...NEW）
- `doom up`はエイリアスとして利用可能
