common-conventional-commits

common-conventional-commits

すべてのコミットメッセージを Conventional Commits 1.0.0 仕様に従って作成してください。構造化された一貫性のあるコミット履歴を作成することで、自動ツールを利用でき、明確なコミュニケーションを実現できます。

使用する場面

次の場合に、このスキルを使用してください。

• コミットメッセージを作成するとき（git commit、インタラクティブリベース、スカッシュなど）
• ユーザーにコミットメッセージを提案するとき
• コミットメッセージをレビューまたは修正するとき
• 作業を複数のコミットに分け、それぞれの内容をどう表現するか決めるとき

手順

1. コミットメッセージの構成

すべてのコミットメッセージは、次の形式に従う必要があります。

<type>[(<ticket-number>)]: <description>

[optional body]

[optional footer(s)]

2. タイプ（必須）

コミットの最初の単語は、変更のカテゴリを表す名詞であるタイプにします。小文字を使用してください。

タイプ	使用する場面
feat	新機能の追加（SemVer の MINOR に相当）
fix	バグの修正（SemVer の PATCH に相当）
docs	ドキュメントのみの変更
style	コードスタイルの変更（フォーマット、空白など）。ロジックの変更はありません
refactor	バグ修正でも機能追加でもないコードの再構成
perf	パフォーマンスの改善
test	テストの追加または修正
build	ビルドシステムまたは外部依存関係の変更
ci	CI 設定ファイルおよびスクリプトの変更
chore	src または test ファイルを変更しない保守作業
revert	以前のコミットを取り消す変更

判断の流れ：

• ユーザーが確認できる新しい機能を追加しますか？ → feat
• 動作しない機能を修正しますか？ → fix
• 動作を変えずにコードの構造を変更しますか？ → refactor
• テストにのみ影響しますか？ → test
• ドキュメントにのみ影響しますか？ → docs
• 速度またはリソース使用量を改善しますか？ → perf
• ビルドまたは CI の設定を変更しますか？ → build または ci
• 上記のいずれにも該当しませんか？ → chore

3. スコープ（任意）

コードベース内で影響を受ける部分を示すために、タイプの後ろの括弧内にスコープを指定できます。スコープには名詞を使用してください。

feat(auth): add OAuth2 login flow
fix(parser): handle empty arrays correctly
docs(readme): update installation instructions

プロジェクト内ではスコープを一貫して使用してください。一般的なスコープには、モジュール名、機能領域、パッケージ名などがあります。

4. チケット番号（推奨）

課題管理システムのチケット番号をコミットのスコープとして含めてください。現在の Git ブランチ名からチケット番号を抽出します。

ルール：

1. git branch --show-current を実行してブランチ名を取得します。
2. チケット番号を抽出します。パターン <PROJECT>-<number> に一致する大文字の識別子です（例：XODO-123、PROJ-42）。
3. チケット番号をタイプの後ろの括弧内のスコープとして使用します。
4. ブランチ名からチケット番号を特定できない場合は、省略します。

// Branch: feat/XODO-123-add-user-registration
feat(XODO-123): add user registration page

// Branch: fix/XODO-456-login-session-expired
fix(XODO-456): resolve login failure when session is expired

// Branch: main (no ticket number)
chore: update dependencies

5. 説明（必須）

説明は、タイプ／スコープの接頭辞（チケット番号がある場合はその番号も含む）の後に、コロンとスペースを置いて続けます。

ルール：

1. 命令形を使用します（「added feature」や「adds feature」ではなく「add feature」）。
2. 最初の文字を大文字にしないでください。
3. 末尾にピリオドを付けないでください。
4. 簡潔にしてください。全体（タイプ＋スコープ＋説明）を 72 文字未満にすることを目指してください。
5. コミットが何をするのかを説明し、どのようにするのかは説明しないでください。

// Bad
feat: Added the new user registration page.
fix: This fixes the bug where users couldn't log in

// Good
feat: add user registration page
fix: resolve login failure when session is expired

6. 本文（任意）

説明の後に空行を 1 行入れて、長めの本文を追加できます。本文では、何を、なぜ行うのかを説明し、どのように行うのかは説明しないでください（どのように行うかは差分を見れば分かります）。

• 自由形式のテキストです。
• 空行で区切られた複数の段落で構成できます。
• 命令形を使用してください。

fix: prevent racing of requests

Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.

Remove timeouts which were used to mitigate the racing issue but are
obsolete now.

7. フッター（任意）

フッターは本文の後に空行を 1 行入れて記述します。各フッターは、トークン、区切り文字（: または #）、値で構成されます。

一般的なフッター：

• BREAKING CHANGE: <description> — 互換性を損なう API 変更を示します（SemVer の MAJOR に相当）
• Refs: #<issue-number> — 関連する課題を参照します
• Reviewed-by: <name> — レビュー担当者を示します
• Co-authored-by: <name> <email> — 共同作成者を示します

フッタートークンでは、スペースの代わりに - を使用します（例：Acked-by）。ただし、BREAKING CHANGE はそのまま使用できます。

8. 破壊的変更

破壊的変更は、次のいずれか（または両方）で示す必要があります。

1. 型／スコープの後、コロンの前に ! を付ける：

   feat!: remove deprecated API endpoints
   feat(api)!: change response format for /users
   

2. BREAKING CHANGE: フッターを付ける：

   feat: change response format for /users
   
   BREAKING CHANGE: the /users endpoint now returns an array instead of an object wrapper
   

! を使用する場合は、BREAKING CHANGE: フッターを省略できます。その場合、説明文が破壊的変更の説明となります。

9. 1つのコミットにつき1つの論理的変更

各コミットには、厳密に1つの論理的変更を含める必要があります。コミットが複数の型に該当する場合は、複数のコミットに分けてください。

• バグ修正とリファクタリングを同じコミットに含めないでください。
• 機能と無関係なスタイル変更を同じコミットに含めないでください。
• これにより、意味のある変更履歴を作成でき、変更をきれいに取り消せます。

10. 例

feat(XODO-123): add email notification on order completion

fix(XODO-456): resolve token refresh loop on expired sessions

docs(XODO-789): correct installation steps for Docker setup

refactor(XODO-101): extract price calculation into dedicated service

feat(XODO-202)!: change pagination response envelope

BREAKING CHANGE: list endpoints now return { data, meta } instead of a flat array

Refs: #452

revert(XODO-123): add email notification on order completion

Refs: 676104e

11. 検証チェックリスト

コミットメッセージを確定する前に、次の点を確認してください。

• 有効な型を小文字で先頭に記載している。
• スコープ（指定する場合）が括弧内の名詞になっている。
• 型／スコープと説明の間がコロンとスペースで区切られている。
• ブランチのチケット番号をスコープとして使用している（利用可能な場合）。
• 説明が命令形で、先頭が小文字、末尾にピリオドがない。
• 1行目の合計が72文字以下である。
• 本文（記載する場合）の前に空行が1行ある。
• 破壊的変更を ! および／または BREAKING CHANGE: フッターで示している。
• コミットが1つの論理的変更を表している。

参考資料

• Conventional Commits 1.0.0