# 画面設計書 21-changelog.sh

## 概要

本ドキュメントは、Oh My Zshの変更履歴生成スクリプト `changelog.sh` の設計仕様を定義する。このスクリプトはGitコミット履歴を解析し、Conventional Commits形式に基づいた構造化された変更履歴を生成するCLIツールである。

### 本画面の処理概要

本スクリプトは、Oh My Zshリポジトリのコミット履歴を解析し、バージョン間の変更内容を人間が読みやすい形式で出力するツールである。

**業務上の目的・背景**：Oh My Zshのユーザーやコントリビューターがバージョンアップ時にどのような変更が行われたかを把握するために必要なツールである。手動で変更履歴を作成する手間を省き、Gitコミット履歴から自動的に構造化されたチェンジログを生成することで、リリース管理の効率化と情報の透明性を実現する。

**画面へのアクセス方法**：以下の2つの方法でアクセス可能
1. `omz changelog [version]` コマンドを実行（lib/cli.zshを経由）
2. 直接 `$ZSH/tools/changelog.sh [until] [since] [--format]` を実行

**主要な操作・処理内容**：
1. 指定されたバージョン範囲のGitコミット履歴を取得
2. 各コミットをConventional Commits形式（type(scope): subject）でパース
3. コミットタイプ別（feat, fix, perf, docs等）に分類
4. BREAKING CHANGE情報を抽出・表示
5. リバートされたコミットを自動検出・除外
6. text/raw/md形式で整形された変更履歴を出力

**画面遷移**：
- 入口：`omz changelog` コマンド（lib/cli.zsh の `_omz::changelog` 関数から呼び出し）
- 出口：標準出力への変更履歴表示（他画面への遷移なし）

**権限による表示制御**：特になし。ただし、Gitリポジトリへの読み取りアクセス権限が必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 16 | omz changelog | 主機能 | 指定バージョン間の変更履歴を生成 |
| 6 | omzコマンド | 補助機能 | omzコマンドの統合CLIインターフェースを通じてチェンジログを表示 |

## 画面種別

CLI出力（テキスト表示）

## URL/ルーティング

```
$ZSH/tools/changelog.sh [until] [since] [--format]
```

または

```
omz changelog [version]
```

## 入出力項目

### 入力パラメータ

| No | パラメータ名 | 位置 | 必須 | デフォルト値 | 説明 |
|----|-------------|------|------|-------------|------|
| 1 | until | $1 | いいえ | HEAD | 変更履歴の終点となるコミット/タグ/ブランチ |
| 2 | since | $2 | いいえ | 前回バージョン or 直前タグ | 変更履歴の起点となるコミット/タグ/ブランチ |
| 3 | format | $3 | いいえ | --text | 出力形式（--text/--raw/--md） |

### 環境変数

| 変数名 | 必須 | 説明 |
|--------|------|------|
| ZSH | はい | Oh My Zshのインストールディレクトリ |
| FORCE_HYPERLINK | いいえ | 0以外でハイパーリンク出力を強制 |
| COLUMNS | いいえ | ターミナル幅（Breaking Change表示時の折り返しに使用） |

## 表示項目

### 出力セクション構成

| No | セクション | 説明 | 条件 |
|----|-----------|------|------|
| 1 | バージョンヘッダ | バージョン名（タグ/ブランチ/コミット） | 常に表示 |
| 2 | BREAKING CHANGES | 破壊的変更の警告メッセージ | 該当コミットがある場合のみ |
| 3 | Features | 新機能（feat:）コミット一覧 | 該当コミットがある場合のみ |
| 4 | Bug fixes | バグ修正（fix:）コミット一覧 | 該当コミットがある場合のみ |
| 5 | Performance | パフォーマンス改善（perf:）コミット一覧 | 該当コミットがある場合のみ |
| 6 | Documentation | ドキュメント（docs:）コミット一覧 | 該当コミットがある場合のみ |
| 7 | Other changes | その他の変更（refactor, style, other） | 該当コミットがある場合のみ |

### 各コミットエントリの表示形式

| 要素 | text形式 | raw形式 | md形式 |
|------|---------|---------|--------|
| ハッシュ | ANSIカラー（黄色）+ハイパーリンク | プレーン7文字 | Markdownリンク |
| スコープ | ANSIカラー（赤）+角括弧 | プレーン角括弧 | プレーン角括弧 |
| サブジェクト | Issue番号をカラーリング | プレーン | Issue番号をMarkdownリンク |

## イベント仕様

### 1-スクリプト実行

**トリガー**: スクリプト実行またはomz changelogコマンド

**処理フロー**:
1. 出力先がTTYかどうか判定し、非TTYの場合は自動的に`--raw`形式を適用
2. `main`関数を呼び出し
3. パラメータを解析し、デフォルト値を設定
4. バージョン名を決定（tag > branch > name-rev > short hash）
5. `git log`でコミット履歴を取得
6. 各コミットに対して`parse-commit`を実行
7. タグ境界を検出したら`display-release`で出力
8. 最後に残りのコミットを`display-release`で出力

### 2-コミットパース

**トリガー**: 各コミットに対するループ処理

**処理内容**:
1. `commit:type`: Conventional Commits形式からタイプを抽出
2. `commit:scope`: スコープ部分を抽出
3. `commit:subject`: サブジェクト（説明文）を抽出
4. `commit:is-breaking`: BREAKING CHANGE情報を検出
5. `commit:is-revert`: リバートコミットを検出

### 3-リリース表示

**トリガー**: タグ境界検出時または最終処理時

**処理内容**:
1. リバートされたコミットを除外
2. 無視タイプのコミットを除外（Breaking Changeがある場合は除く）
3. スコープ幅の最大値を計算（パディング用）
4. バージョンヘッダを表示
5. BREAKING CHANGESセクションを表示
6. 各メインタイプ（feat, fix, perf, docs）のセクションを表示
7. Other changesセクションを表示

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

本スクリプトはデータベースを使用しない。Gitリポジトリからの読み取り専用操作のみを行う。

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| - | - | - | データベース操作なし |

## メッセージ仕様

| No | メッセージ種別 | メッセージ内容 | 表示条件 |
|----|---------------|---------------|----------|
| 1 | 情報 | "No changes to mention." | 表示すべきコミットがない場合 |
| 2 | 情報 | "...more commits omitted" | 35件以上のコミットを切り捨てた場合 |

## 例外処理

| No | 例外状況 | 処理内容 |
|----|---------|----------|
| 1 | 無効なバージョン指定 | lib/cli.zshの_omz::changelog関数でエラーメッセージを表示し終了 |
| 2 | Gitリポジトリ外での実行 | gitコマンドのエラーにより正常に動作しない |
| 3 | 前回バージョンが取得できない | sinceをunsetし、全履歴を対象とする |

## 備考

- Conventional Commits仕様（https://www.conventionalcommits.org/）に準拠したコミットメッセージを前提とする
- 認識されるコミットタイプ: build, chore, ci, docs, feat, fix, perf, refactor, style, test
- ターミナルのハイパーリンク対応は自動検出される（iTerm, WezTerm, VSCode等）
- 非対話的実行（パイプ、リダイレクト）時は自動的にraw形式で出力される

---

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

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

### 推奨読解順序

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

まず、コミット情報を格納する連想配列の構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | changelog.sh | `tools/changelog.sh` | 行12-24: TYPES連想配列でコミットタイプと表示名のマッピングを定義 |
| 1-2 | changelog.sh | `tools/changelog.sh` | 行27-37: MAIN_TYPES, OTHER_TYPES, IGNORED_TYPESでタイプの分類を定義 |

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

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

処理の起点となる関数を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | changelog.sh | `tools/changelog.sh` | 行587-592: スクリプト末尾でTTY判定を行い、main関数を呼び出す |
| 2-2 | changelog.sh | `tools/changelog.sh` | 行483-585: main関数でパラメータ解析とコミット取得を実行 |

**主要処理フロー**:
1. **行588-591**: 標準出力がTTYでなければ`--raw`形式を自動適用
2. **行493-506**: until/sinceパラメータのデフォルト値を設定
3. **行519-522**: バージョン名を決定（describe > symbolic-ref > name-rev > rev-parse）
4. **行533-537**: git logでコミット履歴を取得

#### Step 3: コミットパース処理を理解する

各コミットの解析ロジック。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | changelog.sh | `tools/changelog.sh` | 行43-161: parse-commit関数と内部関数群 |

**主要処理フロー**:
- **行54-68**: `commit:type` - 正規表現でコミットタイプを抽出
- **行70-87**: `commit:scope` - 正規表現でスコープを抽出
- **行89-98**: `commit:subject` - サブジェクトを抽出
- **行101-119**: `commit:is-breaking` - BREAKING CHANGE検出
- **行122-131**: `commit:is-revert` - リバートコミット検出

#### Step 4: 表示処理を理解する

変更履歴の出力ロジック。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | changelog.sh | `tools/changelog.sh` | 行255-481: display-release関数 |
| 4-2 | changelog.sh | `tools/changelog.sh` | 行297-312: fmt:hash関数で出力形式別のハッシュフォーマット |
| 4-3 | changelog.sh | `tools/changelog.sh` | 行317-333: fmt:header関数でヘッダのフォーマット |

**主要処理フロー**:
- **行266-274**: リバートされたコミットを除外
- **行277-280**: 無視タイプのコミットを除外
- **行468-480**: セクション表示順序を制御

#### Step 5: CLI連携を理解する

omzコマンドからの呼び出し経路。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | cli.zsh | `lib/cli.zsh` | 行185-203: _omz::changelog関数でバージョン検証とchangelog.sh呼び出し |

**主要処理フロー**:
- **行188-193**: 指定バージョンの妥当性検証（refs/heads, refs/tags, commit）
- **行202**: ZSH環境変数を設定してchangelog.shを実行

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

```
omz changelog [version]
    |
    +-- _omz::changelog (lib/cli.zsh:185)
            |
            +-- git show-ref --verify (バージョン検証)
            |
            +-- zsh -f "$ZSH/tools/changelog.sh"
                    |
                    +-- main (changelog.sh:483)
                            |
                            +-- git describe/symbolic-ref/name-rev/rev-parse
                            |       (バージョン名決定)
                            |
                            +-- git log (コミット履歴取得)
                            |
                            +-- parse-commit (各コミット解析)
                            |       |
                            |       +-- commit:type
                            |       +-- commit:scope
                            |       +-- commit:subject
                            |       +-- commit:is-breaking
                            |       +-- commit:is-revert
                            |
                            +-- display-release (変更履歴出力)
                                    |
                                    +-- display:version
                                    +-- display:breaking
                                    +-- display:type (feat/fix/perf/docs)
                                    +-- display:others
```

### データフロー図

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

コミットパラメータ        main関数
(until, since, format)    パラメータ解析・デフォルト設定
        |                         |
        v                         v
git log出力        -->    parse-commit関数
(hash, refs,              コミット分類
subject, body)            (types, scopes, subjects,
        |                  breaking, reverts)
        |                         |
        v                         v
                          display-release関数
                          フォーマット・出力
                                  |
                                  v
                          [標準出力]
                          text形式: ANSIカラー付きテキスト
                          raw形式: プレーンテキスト
                          md形式: Markdown
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| changelog.sh | `tools/changelog.sh` | ソース | 変更履歴生成のメインスクリプト |
| cli.zsh | `lib/cli.zsh` | ソース | omz changelogコマンドのエントリーポイント |
| upgrade.sh | `tools/upgrade.sh` | 関連ソース | アップグレード後にchangelog.shを呼び出す |
