# バッチ設計書 5-changelog.sh

## 概要

本ドキュメントは、コミット履歴から変更ログを生成・表示するシェルスクリプト`changelog.sh`のバッチ設計書である。このスクリプトはConventional Commits形式のコミットを解析し、整形された変更ログを出力する。

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

このバッチはGitコミット履歴を解析し、Conventional Commits仕様に基づいて構造化された変更ログを生成する。コミットタイプ（feat、fix、docs等）ごとに分類し、破壊的変更を優先表示する。

**業務上の目的・背景**：Oh My Zshは活発に開発されており、ユーザーがバージョン間の変更内容を把握することは重要である。このスクリプトは、Gitコミットメッセージから意味のある変更ログを自動生成し、ユーザーが新機能、バグ修正、破壊的変更を容易に確認できるようにする。

**バッチの実行タイミング**：ユーザーによる手動実行（`omz changelog`コマンド）、または`upgrade.sh`（No.3）からの自動呼び出し（interactiveモード時）。

**主要な処理内容**：
1. コミット範囲の決定（引数またはoh-my-zsh.lastVersionから）
2. Gitログからコミット情報を取得（ハッシュ、参照、サブジェクト、ボディ）
3. Conventional Commits形式でコミットを解析
   - タイプ（feat、fix、docs等）の抽出
   - スコープの抽出
   - サブジェクトの抽出
   - 破壊的変更の検出
   - リバートコミットの検出
4. リバートされたコミットの除外
5. タイプ別にコミットを分類・表示
6. 出力形式（text/raw/md）に応じたフォーマット

**前後の処理との関連**：`upgrade.sh`（No.3）のinteractiveモードから呼び出される。oh-my-zsh.lastVersionに保存された以前のバージョンを参照する。

**影響範囲**：標準出力への変更ログ表示のみ（ファイル変更なし）

## バッチ種別

レポート生成 / 変更ログ出力

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（手動またはupgrade.shから呼び出し） |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動実行（omz changelog）または自動呼び出し |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Oh My Zshインストール済み | $ZSHディレクトリが存在すること |
| Gitリポジトリ | $ZSHがGitリポジトリであること |

### 実行可否判定

1. $ZSHディレクトリに移動
2. Gitリポジトリでない場合は何も出力しない

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| $1 | 文字列 | No | HEAD | 終了コミット（until） |
| $2 | 文字列 | No | oh-my-zsh.lastVersion または 前のタグ | 開始コミット（since） |
| $3 | 文字列 | No | --text | 出力形式（--text/--raw/--md） |

### Git設定

| 設定項目 | 説明 |
|---------|------|
| oh-my-zsh.lastVersion | 前回更新時のコミットハッシュ |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| Gitログ | Git | コミット履歴 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | テキスト/Markdown | 整形された変更ログ |

### 出力フォーマット

**出力形式の種類：**
- `--text`: ANSIエスケープシーケンスによるカラー表示（デフォルト）
- `--raw`: プレーンテキスト
- `--md`: Markdown形式

**変更ログの構造：**
1. バージョンヘッダー
2. BREAKING CHANGES（破壊的変更）
3. Features（新機能）
4. Bug fixes（バグ修正）
5. Performance（パフォーマンス改善）
6. Documentation（ドキュメント）
7. Other changes（その他の変更）

## 処理フロー

### 処理シーケンス

```
1. 初期化
   ├─ $ZSHディレクトリに移動
   └─ extendedglobオプションを有効化

2. 定数定義
   ├─ TYPES: コミットタイプと表示名のマッピング
   ├─ MAIN_TYPES: メインセクションに表示するタイプ
   ├─ OTHER_TYPES: その他の変更に表示するタイプ
   └─ IGNORED_TYPES: 無視するタイプ

3. main関数
   ├─ 引数解析（until, since, output）
   ├─ sinceの決定
   │   ├─ oh-my-zsh.lastVersion
   │   └─ git describe --tags
   └─ バージョン名の決定

4. Gitログ取得
   └─ git log -z --format（ハッシュ、参照、サブジェクト、ボディ）

5. コミット解析（parse-commit）
   ├─ commit:type - タイプ抽出
   ├─ commit:scope - スコープ抽出
   ├─ commit:subject - サブジェクト抽出
   ├─ commit:is-breaking - 破壊的変更検出
   └─ commit:is-revert - リバート検出

6. リリース表示（display-release）
   ├─ リバートされたコミットを除外
   ├─ 無視タイプを除外（破壊的変更あり以外）
   ├─ display:version - バージョンヘッダー
   ├─ display:breaking - 破壊的変更
   ├─ display:type - 各タイプのコミット
   └─ display:others - その他の変更

7. 出力フォーマット
   ├─ fmt:hash - ハッシュのフォーマット
   ├─ fmt:scope - スコープのフォーマット
   ├─ fmt:subject - サブジェクトのフォーマット
   └─ fmt:header - ヘッダーのフォーマット
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[ディレクトリ移動]
    B --> C[引数解析]
    C --> D{since指定?}
    D -->|No| E[lastVersionまたはタグ取得]
    D -->|Yes| F[指定値使用]
    E --> G[バージョン名決定]
    F --> G
    G --> H[Gitログ取得]
    H --> I[コミットループ開始]
    I --> J{コミットあり?}
    J -->|No| K[display-release]
    J -->|Yes| L[parse-commit]
    L --> M{新しいタグ?}
    M -->|Yes| N[現在のリリース表示]
    M -->|No| O[次のコミット]
    N --> P[コミット配列リセット]
    P --> O
    O --> I
    K --> Q{表示コミットあり?}
    Q -->|Yes| R[変更ログ出力]
    Q -->|No| S["No changes to mention."]
    R --> T[終了]
    S --> T
```

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

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

該当なし（本スクリプトはデータベース操作を行わない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 情報なし | 変更ログに含めるコミットがない | "No changes to mention."を表示 |
| - | 切り捨て | コミット数が多すぎる（35件超、since未指定時） | "...more commits omitted"を表示 |

### リトライ仕様

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

### 障害時対応

該当なし（読み取り専用操作）

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 数十〜数百コミット |
| 目標処理時間 | 数秒以内 |
| メモリ使用量上限 | 通常のシェルスクリプト実行範囲 |

## 排他制御

該当なし（読み取り専用操作）

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 情報出力 | 切り捨て発生時 | "...more commits omitted" |
| 情報出力 | 変更なし時 | "No changes to mention." |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 該当なし | - | - |

## 備考

### Conventional Commits形式

スクリプトは以下のConventional Commits形式を解析する：
```
type[(scope)][!]: subject

body
[BREAKING CHANGE: warning]
```

### サポートされるコミットタイプ

| タイプ | 表示名 | 表示セクション |
|-------|--------|---------------|
| feat | Features | メイン |
| fix | Bug fixes | メイン |
| perf | Performance | メイン |
| docs | Documentation | メイン |
| refactor | Refactor | その他 |
| style | Style | その他 |
| other | - | その他 |
| build | Build system | 無視 |
| chore | Chore | 無視 |
| ci | CI | 無視 |
| test | Testing | 無視 |

### 特殊処理

- 破壊的変更は常に最初に表示される（無視タイプでも表示）
- リバートコミットは、リバートされたコミットとともに除外される
- since未指定時は35コミットで切り捨て
- ハイパーリンクサポートターミナルではコミットハッシュとIssue番号がクリック可能
- 標準出力がTTYでない場合は自動的に--raw形式で出力
