conventional-commits

Conventional Commits

概要

Conventional Commits は、明確なコミット履歴を作成するための明示的な構造をコミットメッセージに定めた仕様です。変更履歴の生成、セマンティックバージョンの更新幅の判断、変更内容の効果的な伝達を自動化するツールに対応できます。

基本原則：すべてのコミットメッセージは、変更の種類と対象範囲を明確に伝える構造化された形式に従います。

コミットメッセージの構造

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

クイックリファレンス

要素	必須	形式	目的
種類	✅ はい	feat、fix、または独自の種類	変更の性質を示します
スコープ	❌ 任意	括弧：(parser)	追加のコンテキストを示します
破壊的変更	❌ 任意	種類／スコープの後に !	破壊的変更を示します
説明	✅ はい	短い要約	変更の簡潔な説明
本文	❌ 任意	自由形式の段落	詳細な説明
フッター	❌ 任意	Token: value 形式	メタデータ（例：BREAKING CHANGE:）

コミットの種類

標準の種類

• feat：新機能（SemVer の MINOR に相当します）
• fix：バグ修正（SemVer の PATCH に相当します）

その他の一般的な種類

• build：ビルドシステムまたは依存関係の変更
• chore：保守作業。本番コードの変更はありません
• ci：CI 設定の変更
• docs：ドキュメントのみの変更
• hotfix：通常の開発ワークフローを介さず、本番環境に直接適用する緊急のバグ修正（SemVer の PATCH に相当します）
• perf：パフォーマンスの改善
• refactor：動作を変更しないコードのリファクタリング
• style：コードスタイルの変更（フォーマット、セミコロンの不足など）
• test：テストの追加または更新

破壊的変更

破壊的変更は、次の 2 つの方法で示せます。

1. 種類／スコープのプレフィックスに記載：コロンの前に ! を付けます

   feat!: remove deprecated API
   feat(api)!: change authentication method
   

2. フッターに記載：BREAKING CHANGE: トークンを使用します

   feat: add new authentication system
   
   BREAKING CHANGE: Old authentication tokens are no longer valid
   

例

基本的な機能追加のコミット

feat: add user authentication endpoint

Implement JWT-based authentication with login and token validation

スコープ付きの機能追加

feat(auth): implement password reset flow

Add forgot password endpoint and email notification system

バグ修正

fix(parser): correct array parsing with multiple spaces

Handle edge case where strings contained multiple consecutive spaces

破壊的変更（プレフィックス）

feat(api)!: remove deprecated v1 endpoints

BREAKING CHANGE: All v1 API endpoints have been removed. Migrate to v2.

破壊的変更（フッター）

feat: update database schema

BREAKING CHANGE: Environment variables now take precedence over config files

ドキュメント

docs: update API reference for authentication endpoints

リファクタリング

refactor(auth): extract token validation to separate module

Improve code organization and testability

パフォーマンス

perf(queries): optimize database query for user lookup

Reduce query time from 500ms to 50ms by adding index

緊急修正

セキュリティの緊急修正

hotfix(auth): fix critical security vulnerability in token validation

Immediate fix for CVE-2024-XXXX. Patch token validation to prevent unauthorized access.

データベースの緊急修正

hotfix(db): fix connection pool exhaustion causing service outage

Emergency patch to increase pool size and add connection timeout. Applied directly to production to restore service.

決済の緊急修正

hotfix(payment): fix incorrect currency conversion in checkout

Critical bug causing incorrect charges. Immediate fix applied to prevent financial impact.

API の緊急修正

hotfix(api): fix null pointer exception in user endpoint

Emergency fix for production crash. Bypassed normal deployment process.

パフォーマンスの緊急修正

hotfix(cache): fix memory leak causing server crashes

Immediate fix for production instability. Applied hotfix to prevent service degradation.

データ整合性の緊急修正

hotfix(data): fix corrupted data migration affecting user accounts

Emergency fix applied directly to production database to prevent data loss.

よくある間違い

❌ コロンとスペースがない

feat add authentication

✅ 正しい例：

feat: add authentication

❌ 種類が大文字

FEAT: add authentication

✅ 正しい例：

feat: add authentication

❌ 説明が長すぎる

feat: add user authentication with JWT tokens, password hashing, session management, and email verification

✅ 正しい例：

feat(auth): implement JWT-based authentication

Add login endpoint, password hashing, session management, and email verification

❌ 種類が間違っている

fix: add new feature for user dashboard

✅ 正しい例：

feat: add user dashboard

❌ 破壊的変更が示されていない

feat(api): remove deprecated endpoints

✅ 正しい例：

feat(api)!: remove deprecated endpoints

BREAKING CHANGE: All v1 endpoints have been removed

❌ スコープに括弧がない

feat auth: implement login

✅ 正しい例：

feat(auth): implement login

ワークフローのガイドライン

コミットを作成するとき

1. 種類を判断する：機能追加、修正、またはその他の種類ですか？
   • 通常の開発ワークフローを介さず、本番環境に直接適用する緊急修正には hotfix を使用します
   • 通常の開発ワークフローで行う通常のバグ修正には fix を使用します
2. スコープを特定する（任意）：コードベースのどの部分が影響を受けますか？
3. 破壊的変更を確認する：この変更によって既存の機能が壊れますか？
4. 簡潔な説明を書く：可能であれば 72 文字以内にします
5. 必要に応じて本文を追加する：背景、動機、詳細を記載します
6. 該当する場合はフッターを含める：破壊的変更、参照情報などを追加します

説明のベストプラクティス

• 命令形を使います。「機能を追加する」とし、「機能を追加した」や「機能を追加する」にはしません
• 末尾にピリオドを付けません
• 簡潔にまとめます（50～72文字が理想です）
• 変更内容に焦点を当てます。理由は本文に記載します

本文のベストプラクティス

• 説明との間に空行を入れます
• 変更の「理由」を説明します
• 背景や状況を説明します
• 関連するイシューや PR を参照します

セマンティックバージョニングとの対応

コミットの種類	SemVer への影響
fix	PATCH（1.0.0 → 1.0.1）
hotfix	PATCH（1.0.0 → 1.0.1）
feat	MINOR（1.0.0 → 1.1.0）
BREAKING CHANGE	MAJOR（1.0.0 → 2.0.0）
その他の種類	自動的なバージョン更新なし

検証チェックリスト

コミットメッセージを確定する前に、次の点を確認します。

• 種類が小文字で、有効な値である
• 種類／スコープの後にコロンとスペースがある
• 説明が簡潔で、命令形になっている
• 破壊的変更が適切に示されている
• 本文が空行で区切られている（本文がある場合）
• フッタートークンにハイフンを使用している（例：BREAKING CHANGE。BREAKING_CHANGEではない）
• タイトルが120文字を超えていない（チームの規定がある場合）

特殊なケース

Revert コミット

revert: let us never again speak of the noodle incident

Refs: 676104e, a215868

1つの機能に対する複数のコミット

1つのコミットが複数の種類に該当する場合は、可能であれば別々のコミットに分けます。

feat(auth): add login endpoint
test(auth): add login endpoint tests
docs(auth): update API documentation for login

ツールとの連携

Conventional Commits により、次のことが可能になります。

• 変更履歴の自動生成：ツールがコミット履歴を解析します
• セマンティックバージョニング：コミットの種類に基づき、バージョンを自動更新します
• リリースノート：コミットから機能や修正を抽出します
• ビルドのトリガー：コミットの種類に応じて、異なるビルドプロセスを実行します

その他のリソース

• reference.md — 公式仕様、コミットの種類、SemVer との対応、ツール — インデックス対象
• 公式仕様：https://www.conventionalcommits.org/en/v1.0.0/

仕様の参照先

このスキルは、公式の Conventional Commits 仕様 v1.0.0 に基づいています。

このスキルに記載されているすべてのルール、例、ガイドラインは、公式仕様に準拠しています。仕様全文、例、FAQ については、公式ドキュメントを参照してください。