# 画面設計書 2-omz changelog

## 概要

本ドキュメントは、Oh My Zshの`omz changelog`コマンドインターフェースの画面設計書です。指定されたバージョンまでの変更履歴を表示する機能を定義します。

### 本画面の処理概要

`omz changelog`コマンドは、Oh My Zshの変更履歴（チェンジログ）を表示するためのコマンドです。Gitのコミット履歴を解析し、Conventional Commits形式に基づいて整形された変更一覧を提供します。

**業務上の目的・背景**：Oh My Zshは活発に開発されており、頻繁にアップデートが行われます。ユーザーがアップデート前後で何が変更されたかを把握し、新機能の活用やBreaking Changesへの対応を行えるよう、変更履歴の確認機能が必要です。この機能により、ユーザーは安心してアップデートを実行でき、問題発生時のトラブルシューティングも容易になります。

**画面へのアクセス方法**：ターミナルで以下のコマンドを実行します。
- `omz changelog` - 最新の変更履歴を表示（前回のバージョンからHEADまで）
- `omz changelog <version>` - 指定バージョンまでの変更履歴を表示

**主要な操作・処理内容**：
1. 指定されたバージョン（またはHEAD）が有効なGit参照かを検証
2. `tools/changelog.sh`スクリプトを呼び出して変更履歴を生成
3. コミットをConventional Commits形式に基づいて分類（feat、fix、perf、docs等）
4. Breaking Changesを優先的に表示
5. ターミナルがハイパーリンクをサポートしている場合、コミットハッシュやIssue番号をクリック可能なリンクとして表示

**画面遷移**：
- 遷移元：`omz`コマンドから
- 遷移先：表示完了後、シェルプロンプトに戻る

**権限による表示制御**：なし。すべてのユーザーが同一の変更履歴を参照できます。ただし、Gitリポジトリへのアクセス権が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | omzコマンド | 主機能 | omzコマンドの統合CLIインターフェースを通じてチェンジログを表示 |
| 16 | omz changelog | 主機能 | 指定バージョンまでのチェンジログを表示する処理を実行 |

## 画面種別

情報表示（チェンジログ/履歴表示）

## URL/ルーティング

```
omz changelog [version]
```

## 入出力項目

### 入力項目

| 項目名 | 型 | 必須 | 説明 | デフォルト |
|--------|-----|------|------|-----------|
| version | string | いいえ | Git参照（タグ、ブランチ、コミットハッシュ） | HEAD |

### 出力項目

| 項目名 | 出力先 | 説明 |
|--------|--------|------|
| 変更履歴 | 標準出力（stdout） | 整形されたチェンジログ |
| エラーメッセージ | 標準エラー出力（stderr） | 無効なバージョン指定時のエラー |

## 表示項目

| 項目 | 説明 | 表示形式 |
|------|------|----------|
| バージョンヘッダー | 表示対象のバージョン名 | 下線付きテキスト |
| BREAKING CHANGES | 破壊的変更の一覧 | 赤色テキスト、詳細説明付き |
| Features | 新機能の一覧 | スコープ付きリスト |
| Bug fixes | バグ修正の一覧 | スコープ付きリスト |
| Performance | パフォーマンス改善の一覧 | スコープ付きリスト |
| Documentation | ドキュメント変更の一覧 | スコープ付きリスト |
| Other changes | その他の変更の一覧 | タイプ付きリスト |
| コミットハッシュ | 7文字の短縮ハッシュ | 黄色テキスト（リンク対応時はクリック可能） |
| Issue番号 | GitHub Issue/PR番号 | 緑色テキスト（リンク対応時はクリック可能） |

## イベント仕様

### 1-チェンジログ表示イベント

**トリガー**：`omz changelog [version]`コマンドの実行

**処理フロー**：
1. バージョン引数のバリデーション（Git参照として有効か確認）
2. `tools/changelog.sh`を別プロセスで実行
3. Gitログからコミット情報を取得
4. コミットをConventional Commits形式に基づいてパース
5. タイプ別に分類・整形して出力

**データの流れ**：
```
ユーザー入力 → _omz::changelog → changelog.sh → git log → parse-commit → display-release → stdout
```

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| チェンジログ表示 | なし | - | データベース操作なし |

本コマンドは情報表示のみを行い、ファイルシステムやデータベースへの変更は発生しません。Gitリポジトリからの読み取りのみ行います。

## メッセージ仕様

| メッセージ種別 | メッセージ内容 | 表示条件 |
|---------------|---------------|----------|
| 使用方法 | `Usage: omz changelog [version]` | 無効なバージョン指定時 |
| 注意 | `NOTE: <version> must be a valid branch, tag or commit.` | 無効なバージョン指定時 |
| 情報 | `No changes to mention.` | 表示すべき変更がない場合 |
| 情報 | `...more commits omitted` | コミット数が35を超えた場合 |

## 例外処理

| 例外状態 | 処理内容 | 戻り値 |
|----------|----------|--------|
| 無効なバージョン指定 | 使用方法を表示して終了 | 1 |
| Gitリポジトリでない | changelog.shがエラー終了 | 非0 |
| Git参照が見つからない | エラーメッセージを表示 | 1 |

## 備考

- 出力フォーマットは3種類：text（デフォルト、ANSI色付き）、raw（プレーンテキスト）、md（Markdown）
- パイプ出力時は自動的にraw形式になる
- ターミナルがハイパーリンクをサポートしている場合、コミットハッシュやIssue番号がクリック可能なリンクになる
- Conventional Commits形式（`type(scope): subject`）に従ったコミットのみが適切に分類される
- 35コミットを超える場合は自動的に省略される（`--all`指定で全件表示可能）

---

## コードリーディングガイド

本画面を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

チェンジログ機能で使用される主要なデータ構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | changelog.sh | `tools/changelog.sh` | 行12-24でTYPES連想配列（コミットタイプの定義）を確認 |
| 1-2 | changelog.sh | `tools/changelog.sh` | 行26-37でMAIN_TYPES、OTHER_TYPES、IGNORED_TYPESの分類を確認 |

**読解のコツ**: zshの連想配列は`local -A name`で宣言され、`name=(key1 value1 key2 value2)`形式で初期化されます。

#### Step 2: エントリーポイントを理解する

CLIからチェンジログ機能がどのように呼び出されるかを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | cli.zsh | `lib/cli.zsh` | `_omz::changelog`関数（185-203行目）がエントリーポイント |

**主要処理フロー**:
1. **行186**: バージョン引数をデフォルトHEADで取得
2. **行188-193**: Git参照として有効かを検証（ブランチ、タグ、コミットのいずれか）
3. **行194-199**: 無効な場合は使用方法を表示して終了
4. **行202**: `tools/changelog.sh`を別シェルで実行

#### Step 3: チェンジログ生成ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | changelog.sh | `tools/changelog.sh` | main関数（483-585行目）でメインロジックを確認 |
| 3-2 | changelog.sh | `tools/changelog.sh` | parse-commit関数（43-161行目）でコミット解析ロジックを確認 |
| 3-3 | changelog.sh | `tools/changelog.sh` | display-release関数（255-481行目）で表示ロジックを確認 |

**主要処理フロー**:
- **行493-506**: since（開始バージョン）の決定ロジック
- **行533-537**: Gitログからコミット情報を取得
- **行541-573**: 各コミットをパースしてタイプ別に分類
- **行575**: display-release関数で整形・出力

#### Step 4: 表示フォーマット関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | changelog.sh | `tools/changelog.sh` | fmt:hash（297-312行目）でハッシュの整形を確認 |
| 4-2 | changelog.sh | `tools/changelog.sh` | fmt:subject（363-382行目）でサブジェクトの整形とリンク化を確認 |
| 4-3 | changelog.sh | `tools/changelog.sh` | supports_hyperlinks（201-249行目）でターミナルのリンク対応判定を確認 |

### プログラム呼び出し階層図

```
omz changelog [version]
    │
    └─ _omz::changelog (lib/cli.zsh)
           │
           ├─ git show-ref / rev-parse (バージョン検証)
           │
           └─ zsh -f "$ZSH/tools/changelog.sh"
                  │
                  └─ main
                         │
                         ├─ git describe / symbolic-ref (バージョン名取得)
                         │
                         ├─ git log (コミット情報取得)
                         │
                         ├─ parse-commit (各コミット解析)
                         │      ├─ commit:type
                         │      ├─ commit:scope
                         │      ├─ commit:subject
                         │      ├─ commit:is-breaking
                         │      └─ commit:is-revert
                         │
                         └─ display-release (整形・出力)
                                ├─ display:version
                                ├─ display:breaking
                                ├─ display:type (MAIN_TYPES各タイプ)
                                └─ display:others
```

### データフロー図

```
[入力]                    [処理]                         [出力]

version引数 ───▶ _omz::changelog ───▶ バージョン検証
                                              │
                                              ▼
                      changelog.sh ◀── 有効なバージョン
                           │
                           ▼
                       git log ───▶ コミット情報
                           │
                           ▼
                    parse-commit ───▶ 分類済みコミット
                           │            (types, subjects,
                           │             scopes, breaking)
                           ▼
                   display-release ───▶ stdout
                                         │
                                         ▼
                                   整形されたチェンジログ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| cli.zsh | `lib/cli.zsh` | ソース | omz changelogコマンドのエントリーポイント |
| changelog.sh | `tools/changelog.sh` | ソース | チェンジログ生成のメインロジック |
| oh-my-zsh.sh | `oh-my-zsh.sh` | ソース | Oh My Zsh初期化時にcli.zshを読み込む |
