Conventional Commits with Gitmoji

# Conventional Commits with Gitmoji ドキュメント

本ドキュメントでは、チームで **Conventional Commits** を導入するときのポイントや、VS Code 拡張機能・Gitmoji との組み合わせ方法をまとめます。

## 1. Conventional Commits とは

**Conventional Commits** は、コミットメッセージに一定の規則を設けることで、変更履歴を自動解析しやすくし、以下のようなメリットをもたらす規約です。

- **CHANGELOG** の自動生成が容易になる
- **セマンティック バージョニング (SemVer)** に基づく自動バージョンアップが可能
- 変更内容を簡潔かつ分かりやすく伝えられる
- CI/CD やリリースワークフローを自動化しやすくなる

## 2. 目的と導入メリット

1. **一貫性のあるコミットメッセージ**
   - 誰が見てもコミットの意図がひと目でわかる
2. **セマンティック バージョニングとの連携**
   - `fix` -> パッチリリース (PATCH)
   - `feat` -> マイナーリリース (MINOR)
   - `BREAKING CHANGE` -> メジャーリリース (MAJOR)
3. **自動化のしやすさ**
   - リリースノート生成、バージョン更新、ビルドやデプロイなどの自動化を促進
4. **開発者体験 (DX) の向上**
   - チーム全員がコミット内容を把握しやすく、新規参加者にも優しい

## 3. VS Code 拡張機能「Conventional Commits」

VS Code 拡張機能を利用することで、簡単に始めることができます。

> [**Conventional Commits** (by vivaxy)](https://marketplace.visualstudio.com/items?itemName=vivaxy.vscode-conventional-commits)

### 3.1 機能概要

- コマンドパレットから簡単に `type` や `scope`、`description` を入力できるインターフェースを提供
- コミットメッセージのフォーマットを自動補完
- 破壊的変更の指定 (! や BREAKING CHANGE) もサポート

### 3.2 インストール手順

1. VS Code の「拡張機能」ビューを開く
2. `vivaxy conventional commits` で検索
3. 「Install」ボタンをクリックしてインストール
4. 拡張機能が有効になっていることを確認

### 3.3 使い方

1. 変更ファイルをステージング (`git add .` など)
2. VS Code のコマンドパレット（`Ctrl + Shift + P` または `Cmd + Shift + P`）を開く
3. **Conventional Commits** を選択
4. プロンプトに沿って `type`, `scope`, `description` などを入力
5. 必要に応じて body や footer、Gitmoji を含めたコミットメッセージを完成させる
6. コミットを実行

## 4. Conventional Commits の基本構文

```
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

- **type**: feat, fix, docs, style など (詳細は後述)
- **scope** (任意): 対象となるモジュールやコンポーネント名を `( )` で囲んで指定
- **description**: 変更内容を短文で説明
- **body** (任意): 詳細な説明や背景情報などを記載 (空行を挟んで複数段落 OK)
- **footer** (任意): Issue 参照や `BREAKING CHANGE: ...` などを記載

### 4.1 破壊的変更（Breaking Change）の記述方法

1. `type!` で明示する (例: `feat!: ...`)
2. footer に `BREAKING CHANGE: ...` と記述

どちらか一方または両方の書き方で **メジャーリリース** 判定が可能です。

## 5. type 一覧

**type** は以下のとおりです。
 (セマンティック バージョニング上の自動バージョン更新対象は `feat`, `fix`, および `BREAKING CHANGE` のみ)

1. **feat**: 新機能や目に見える拡張
2. **fix**: バグ修正やセキュリティ修正
3. **docs**: ドキュメントやコメント変更
4. **style**: コードやUIの見た目・書式のみの変更
5. **refactor**: コードの再構成（機能・動作は変えない）
6. **perf**: パフォーマンス改善
7. **test**: テストの追加・更新
8. **build**: ビルドシステムや依存関係の変更
9. **ci**: CI（継続的インテグレーション）関連の変更
10. **chore**: 上記いずれにも当てはまらない雑多な変更
11. **revert**: 以前のコミットを元に戻す

## 6. Gitmoji の活用

**Gitmoji** をコミットメッセージ内で活用すると、変更内容を視覚的に分かりやすくなります。
以下に、type 別に主に利用される絵文字を記載します。

### 6.1 feat (新機能)

機能追加やユーザーにとって目に見える変更・拡張など。

| Emoji | コード          | 英語 (原文)                                     | 日本語訳                                        |
| ----- | -------------- | ---------------------------------------------- | ----------------------------------------------- |
| 🎉    | `:tada:`        | Begin a project.                              | プロジェクトを開始する                          |
| 📈    | `:chart_with_upwards_trend:` | Add or update analytics or track code.             | アナリティクスやトラッキングコードを追加・更新する |
| 🌐    | `:globe_with_meridians:` | Internationalization and localization.             | 多言語対応・ローカライズ対応                    |
| 🍱    | `:bento:`       | Add or update assets.                          | 画像や動画などのアセットを追加・更新する        |
| ♿️    | `:wheelchair:`  | Improve accessibility.                         | アクセシビリティを改善する                      |
| 💬    | `:speech_balloon:` | Add or update text and literals.             | テキストや文字列を追加・更新する                |
| 🗃️    | `:card_file_box:` | Perform database related changes.            | データベース関連の変更を行う                    |
| 🚸    | `:children_crossing:` | Improve user experience / usability.       | ユーザーエクスペリエンスや使い勝手を改善する    |
| 📱    | `:iphone:`       | Work on responsive design.                    | レスポンシブデザインを扱う                      |
| 🥚    | `:egg:`          | Add or update an easter egg.                  | イースターエッグを追加・更新する                |
| 🔍️   | `:mag:`          | Improve SEO.                                  | SEO を改善する                                  |
| 💫    | `:dizzy:`        | Add or update animations and transitions.     | アニメーションやトランジションを追加・更新する  |
| 🛂    | `:passport_control:` | Work on code related to authorization, roles and permissions. | 認可・ロール・権限管理に関するコードを実装・修正する |
| 👔    | `:necktie:`      | Add or update business logic.                | ビジネスロジックを追加・更新する                |
| 🩺    | `:stethoscope:`  | Add or update healthcheck.                   | ヘルスチェックを追加・更新する                  |

### 6.2 fix (バグ修正)

既存機能の不具合修正や、壊れた挙動を直す変更など。

| Emoji | コード                    | 英語 (原文)                                | 日本語訳                                 |
| ----- | ------------------------- | ------------------------------------------ | ---------------------------------------- |
| 🐛    | `:bug:`                   | Fix a bug.                                 | バグを修正する                           |
| 🚑️   | `:ambulance:`             | Critical hotfix.                          | 緊急の修正                               |
| 🔒    | `:lock:`                  | Fix security issues.                      | セキュリティ問題を修正する               |
| 🚨    | `:rotating_light:`        | Fix compiler / linter warnings.           | コンパイラやリンターの警告を修正する     |
| 👽    | `:alien:`                 | Update code due to external API changes.  | 外部 API の変更に対応してコードを修正する|
| 🥅    | `:goal_net:`              | Catch errors.                             | エラーをキャッチして処理する             |

### 6.3 docs (ドキュメント)

ドキュメントやコメント、ライセンス、コントリビューター情報など、ドキュメンテーションに関する変更。

| Emoji | コード                  | 英語 (原文)                        | 日本語訳                                       |
| ----- | ----------------------- | ---------------------------------- | ---------------------------------------------- |
| 📝    | `:memo:`                | Add or update documentation.       | ドキュメントを追加・更新する                   |
| ✏️    | `:pencil2:`             | Fix typos.                         | 誤字を修正する                                 |
| 📄    | `:page_facing_up:`      | Add or update license.             | ライセンスを追加・更新する                     |
| 💡    | `:bulb:`                | Add or update comments in source code. | ソースコードのコメントを追加・更新する      |
| 👥    | `:busts_in_silhouette:` | Add or update contributor(s).      | コントリビューターを追加・更新する             |
| 🧑‍🏫  | `:teacher:`             | Add or update educational content. | 教育用コンテンツを追加・更新する               |

### 6.4 style (スタイル)

コードのフォーマットや見た目のみの修正など、機能やロジックに影響しない変更。

| Emoji | コード        | 英語 (原文)                                 | 日本語訳                               |
| ----- | ------------ | ------------------------------------------- | -------------------------------------- |
| 🎨    | `:art:`       | Improve structure / format of the code.     | コードの構造やフォーマットを改善する   |
| 🧑‍🎨  | `:artist:`    | Add or update UI styles.                    | UI のスタイルを追加・更新する           |
| ✏️ | `:pencil2:` | Fix typos. | 誤字を修正する (ソースコードの場合) |

### 6.5 refactor (リファクタリング)

バグ修正でも新機能でもない、動作を変えずにコードを整理・改善する変更。

| Emoji | コード                    | 英語 (原文)                                     | 日本語訳                                   |
| ----- | ------------------------- | ---------------------------------------------- | ------------------------------------------ |
| 🔥    | `:fire:`                  | Remove code or files.                          | コードやファイルを削除する                 |
| ♻️    | `:recycle:`               | Refactor code.                                 | コードをリファクタリングする               |
| 🚚    | `:truck:`                 | Move or rename resources.                      | リソースを移動 / リネームする              |
| 🏗️   | `:building_construction:` | Make architectural changes.                    | アーキテクチャの変更を行う                 |
| 🏷️   | `:label:`                 | Add or update types.                           | 型定義を追加・更新する                     |
| 🗑️   | `:wastebasket:`           | Deprecate code that needs to be cleaned up.    | 今後削除予定のコードを非推奨にする         |
| ⚰️   | `:coffin:`                 | Remove dead code.                              | 使われていないコードを削除する             |

### 6.6 perf (パフォーマンス改善)

パフォーマンスを向上させるための変更。

| Emoji | コード       | 英語 (原文)            | 日本語訳                           |
| ----- | ----------- | ---------------------- | ---------------------------------- |
| ⚡️   | `:zap:`      | Improve performance.   | パフォーマンスを向上させる         |
| 🏎️   | `:racing_car:` | Improve performance.   | パフォーマンスをさらに改善する     |


### 6.7 test (テスト)

テストの追加・修正など。

| Emoji | コード                    | 英語 (原文)                                                 | 日本語訳                                          |
| ----- | ------------------------- | ----------------------------------------------------------- | ------------------------------------------------- |
| ✅    | `:white_check_mark:`      | Add or update tests.                                       | テストを追加・更新する                            |
| 🤡    | `:clown_face:`            | Mock things.                                               | モックを作成・更新する                            |
| 📸    | `:camera_flash:`          | Add or update snapshots.                                   | スナップショットを追加・更新する                  |
| 🥽    | `:goggles:`               | Add or update tests related to security or cryptography.   | セキュリティや暗号に関連するテストを追加・更新する|
| ⚖️   | `:balance_scale:`         | Add or update tests for legal or licensing aspects.        | 法的・ライセンス上のテストを追加・更新する        |
| 🧪    | `:test_tube:`             | Add a failing test.                                        | あえて失敗するテストを追加する                    |

### 6.8 build (ビルド)

ビルドシステムや依存関係、パッケージなどに関する変更。

| Emoji | コード                 | 英語 (原文)                                      | 日本語訳                                          |
| ----- | ---------------------- | ------------------------------------------------ | ------------------------------------------------- |
| ⬇️   | `:arrow_down:`         | Downgrade dependencies.                          | 依存関係をダウングレードする                      |
| ⬆️   | `:arrow_up:`           | Upgrade dependencies.                            | 依存関係をアップグレードする                      |
| 📌    | `:pushpin:`            | Pin dependencies to specific versions.           | 依存関係を特定バージョンに固定する                |
| ➕    | `:heavy_plus_sign:`    | Add a dependency.                                | 依存関係を追加する                                |
| ➖    | `:heavy_minus_sign:`   | Remove a dependency.                             | 依存関係を削除する                                |
| 📦    | `:package:`            | Add or update compiled files or packages.        | コンパイル済みファイルやパッケージを追加・更新する|
| 🐳    | `:whale:`              | Work on Docker.                                  | Docker まわりの作業をする                         |
| 🧑‍🔧  | `:mechanic:`           | Add or update code related to tooling.           | ツールに関連するコードを追加・更新する            |
| 🧑‍🏭  | `:factory_worker:`     | Add or update code related to build processes.   | ビルドプロセスに関連するコードを追加・更新する    |
| 🧑‍🚀  | `:astronaut:`          | Add or update code related to deployment.        | デプロイに関連するコードを追加・更新する          |
| 🧱    | `:bricks:`             | Infrastructure related changes.                  | インフラストラクチャに関する変更を行う            |

### 6.9 ci (継続的インテグレーション)

CI（Continuous Integration）や関連する設定・スクリプトの変更。

| Emoji | コード                     | 英語 (原文)                        | 日本語訳                                  |
| ----- | -------------------------- | ---------------------------------- | ----------------------------------------- |
| 💚    | `:green_heart:`            | Fix CI build.                      | CI のビルドを修正する                     |
| 👷    | `:construction_worker:`    | Add or update CI build system.     | CI ビルドシステムを追加・更新する         |
| 🧑‍✈️  | `:pilot:`                  | Add or update code related to automation. | 自動化に関連するコードを追加・更新する (CI用途など) |

### 6.10 chore (その他)

ソースコードやテストには直接影響しない雑多な作業、またはビジネスロジックや新機能でもない小変更など。

| Emoji | コード                       | 英語 (原文)                                             | 日本語訳                                     |
| ----- | ---------------------------- | ------------------------------------------------------- | -------------------------------------------- |
| 🚀    | `:rocket:`                   | Deploy stuff.                                          | デプロイを行う（※ビルドやCI以外の作業として分類） |
| 🔐    | `:closed_lock_with_key:`     | Add or update secrets.                                 | 秘密情報を追加・更新する                     |
| 🔖    | `:bookmark:`                 | Release / Version tags.                                | リリース用やバージョン用のタグを付ける        |
| 🚧    | `:construction:`             | Work in progress.                                      | 作業中 (WIP)                                 |
| 🔧    | `:wrench:`                   | Add or update configuration files.                     | 設定ファイルを追加・更新する                 |
| 🔨    | `:hammer:`                   | Add or update development scripts.                     | 開発用スクリプトを追加・更新する             |
| 💩    | `:poop:`                     | Write bad code that needs to be improved.              | 改善が必要な悪いコードを書く (ジョーク)      |
| 🔀    | `:twisted_rightwards_arrows:`| Merge branches.                                        | ブランチをマージする                         |
| 🍻    | `:beers:`                    | Write code drunkenly.                                  | 酔った状態でコードを書く (ジョーク)          |
| 🔊    | `:loud_sound:`               | Add or update logs.                                    | ログ出力を追加・更新する                     |
| 🔇    | `:mute:`                     | Remove logs.                                           | ログ出力を削除する                           |
| 🙈    | `:see_no_evil:`              | Add or update a .gitignore file.                       | `.gitignore` を追加・更新する               |
| ⚗️   | `:alembic:`                   | Perform experiments.                                   | 実験的な実装をする                           |
| 🌱    | `:seedling:`                 | Add or update seed files.                              | シードファイルを追加・更新する               |
| 🧐    | `:monocle_face:`             | Data exploration/inspection.                           | データの探索・検証を行う                     |
| 🧑‍💻 | `:technologist:`             | Improve developer experience.                          | 開発者体験(DX) を改善する                    |
| 🧑‍🔬 | `:scientist:`                | Add or update code related to experiments.             | 実験に関連するコードを追加・更新する         |

### 6.11 revert (元に戻す)

以前のコミットを取り消す場合など。

| Emoji | コード        | 英語 (原文)        | 日本語訳       |
| ----- | ------------ | ------------------ | -------------- |
| ⏪    | `:rewind:`    | Revert changes.    | 変更を元に戻す |

## 7. コミットメッセージ例

1. **新機能追加 (feat) + Gitmoji**

   ```
   feat: :tada: プロジェクトを初期セットアップ
   ```

   - `type`: feat
   - Gitmoji: `:tada:` (プロジェクト開始や大きな節目)

2. **バグ修正 (fix) + 破壊的変更 (Breaking Change)**

   ```
   fix!: :bug: ログイン時の致命的なバグを修正
   
   BREAKING CHANGE: ログイン API のエンドポイントを変更しました
   ```

   - `type!`: fix! (破壊的変更)
   - Gitmoji: `:bug:` (一般的なバグ修正)
   - footer で `BREAKING CHANGE` を明示

3. **ドキュメント修正 (docs) + ボディあり**

   ```
   docs: :memo: 使用方法ドキュメントを追記
   
   変更点:
   - インストール手順を詳細化
   - 環境変数のサンプルを追加
   ```

   - `type`: docs
   - Gitmoji: `:memo:`

4. **スタイル修正 (style)**

   ```
   style: :art: コードフォーマットを Prettier で自動整形
   ```

5. **リファクタ (refactor) + scope 指定**

   ```
   refactor(auth): :recycle: 認証ロジックをクラスベースにリファクタリング
   ```

6. **ビルド変更 (build)**

   ```
   build: :arrow_up: TypeScript を 4.x にアップグレード
   ```

## 8. 運用上の注意

1. **コミットを小さく保つ**
   - 1つのコミットで複数の関係ない変更をまとめない
2. **コミットタイプの誤り**
   - マージ前なら `git rebase -i` で修正
   - リリース後はツールやプロセスに応じて対応
3. **すべてのコミッターに強要はしない**
   - 必要に応じてスクワッシュ (squash) やリードメンテナーがコミットメッセージを修正してもよい
4. **拡張ルールはセマンティック バージョニングで管理**
   - チーム独自のタイプ追加などを行う場合は、必要に応じてドキュメント化する

## 9. まとめ

- **Conventional Commits** はコミットメッセージの規約化により、開発効率とリリース管理を向上させる仕組み
- VS Code 拡張機能 (vivaxy) を活用することで、入力補助やテンプレートが利用可能
- **Gitmoji** を組み合わせることで、コミット内容を視覚的・直感的に把握しやすくなる
- `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert` の 11 タイプを採用
- 破壊的変更がある場合は `!` や `BREAKING CHANGE: ...` を必ず明示すること


## 参考リンク

- [Conventional Commits 公式ドキュメント](https://www.conventionalcommits.org/)
- [VS Code 拡張機能 - Conventional Commits (vivaxy)](https://marketplace.visualstudio.com/items?itemName=vivaxy.vscode-conventional-commits)
- [Gitmoji 公式サイト](https://gitmoji.dev/)
- [Semantic Versioning (SemVer)](https://semver.org/)