conventional-commits

Conventional Commits

Git コミットメッセージを作成するとき、またはプルリクエストにタイトルを付けるときは、必ずこの機能を使用してください。Conventional Commits v1.0.0 の規約を示します。これは、リリースツールが解析でき、人が git log --oneline でひと目で確認できるヘッダー形式と、形式に誤りのあるヘッダーが取り込まれる前に検出する実行可能なバリデーターを備えています。以下の規範的なルールは仕様を要約したものなので、適用にあたってネットワークへのアクセスは不要です。

このスキルは自己完結型です。特定のリポジトリに固有のファイルや構成を指定せず、ここに示す規約はどこにインストールしても同じです。ホストプロジェクトがルールを限定している場合（制限されたタイプ一覧、必須スコープ、独自ツールが読み取るコミットトレーラーなど）は、その点についてホスト側の規約に従い、以下の構造は維持してください。

この文書に記載されている「MUST」、「MUST NOT」、「REQUIRED」、「SHALL」、「SHALL NOT」、「SHOULD」、「SHOULD NOT」、「RECOMMENDED」、「MAY」、「OPTIONAL」というキーワードは、RFC 2119 に記載されているとおりに解釈してください。

全体の形式

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

[optional body]

[optional footer(s)]

ガイドライン：

• すべてのコミットの先頭には <type> を付け、その後に任意のスコープ、任意の ! 破壊的変更マーカー、必須のコロン、説明の前に必須の半角スペースを続ける必要があります。
• 先頭行（ヘッダー：type(scope)!: description）は、末尾にピリオドを付けず、1 行に収める必要があります。
• ヘッダー、本文、フッターがある場合は、それぞれの間を空行 1 行で区切る必要があります。

プルリクエストのタイトル

ヘッダー形式はコミットだけに適用されるものではありません。プルリクエストのタイトルも、コミットのヘッダーと同じ <type>[scope][!]: <description> 形式にする必要があります。これにより、マージ方法にかかわらず、タイトルの一貫性と一覧性が保たれます。マージ時にも重要です。スカッシュマージでは一般に、プルリクエストのタイトルがスカッシュ後のコミットの件名として使われるためです（GitHub では、複数コミットの PR の場合はデフォルトで、また「Default to pull request title」が有効な場合はすべての PR で使われます）。タイプの接頭辞がないタイトルを使うと、デフォルトブランチに規約に沿わないコミットが取り込まれます。タイトルに含めるのはヘッダーのみです。本文とフッターはプルリクエストの説明に記載します。本文を書く際は、プロジェクトのプルリクエスト説明文の作成規約を参照してください。

ガイドライン：

• すべてのプルリクエストに Conventional Commits のヘッダー（<type>[scope][!]: <description>）をタイトルとして付け、以下の Type、Scope、Description、Breaking-Change のルールをコミットヘッダーと同様に正確に適用する必要があります。
• 複数のタイプにまたがるプルリクエストでは、主な変更内容に基づいてタイプを選ぶことが望ましいです（例：主に CI 設定を変更し、付随的にドキュメントを修正する場合は ci）。
• このルールをイシューのタイトルに適用してはなりません。イシューでは問題や成果物を平易な説明文で示し、コミットの件名の形式にはしません。

種別

種別のプレフィックスは、リリースのバージョン更新を導き出すためにツールが読み取るため、変更の実態を示す必要があります。

ガイドライン：

• ユーザー向けの機能を追加するコミットでは、feat を必ず使用します。SemVer の MINOR 更新に相当します。
• ユーザー向けのバグを修正するコミットでは、fix を必ず使用します。SemVer の PATCH 更新に相当します。
• リリースに影響しない変更には、次の追加の種別を使用してもかまいません。
  • build — ビルドシステムまたは外部依存関係（依存関係マニフェストやビルド設定など）。
  • chore — ほかの種別に当てはまらない保守作業（スキルの編集、設定の微調整、リポジトリのメタデータなど）。
  • ci — CI/CD の設定（パイプラインの定義やホスティング／プロジェクトの設定など）。
  • docs — ドキュメントのみの変更（README、コントリビューター向けドキュメント、エージェントスキルのドキュメントなど）。
  • style — 動作の変更を伴わない書式や空白のみの変更（通常はフォーマッターによるもの）。
  • refactor — バグ修正にも機能追加にも当たらないコード変更。
  • perf — パフォーマンスの改善。
  • test — テストの追加または修正。
  • revert — 以前のコミットを取り消す変更。以下の取り消しの例を参照してください。
• パース時には種別の大文字・小文字を区別せずに扱う必要がありますが、既存の git log との一貫性を保つため、小文字で記述することを推奨します。

スコープ

スコープは、差分を開かなくてもコードベースのどの部分が変更されたかを読み手に伝えます。便利ですが、主となる領域が明確に一つある場合に限って使用します。

ガイドライン：

• 種別の直後に、括弧で囲んだスコープを含めてもかまいません（例：fix(parser): ...）。
• スコープには、影響を受けるコードベースの領域を示す名詞を使用する必要があります。既存の構成に合った名前（api、auth、config、e2e、skills、または特定のモジュール名やルート名など）を優先してください。
• 変更がプロジェクト全体に及び、主となる領域が一つに定まらない場合は、スコープを省略することを推奨します。

説明

説明は git log --oneline に表示される一行であり、命令形にすることでコミットが実行する内容として読めます。

ガイドライン：

• 説明は : の直後に置き、変更を短く要約した命令形にする必要があります（例：「ポーランド語を追加する」。過去形の「追加した」や三人称単数の「追加する」は使用しません）。
• git log --oneline で読みやすくなるよう、ヘッダー全体（type(scope)!: description）は約72文字以内にすることを推奨します。
• 説明の末尾にピリオドを付けてはいけません。

本文

差分を見れば変更内容はわかります。本文には、コードだけでは伝えられない理由を記し、次の読み手に引き継ぎます。

ガイドライン：

• 説明の後に空行を一つ挟み、背景、理由、移行に関する注意事項を本文に記載してもかまいません。変更の「理由」が差分から明らかでない場合は、本文を記載してください。
• 本文は、改行で区切られた任意の数の段落で構成できます。本文の形式は自由です。
• URL とコードスパンを除き、ターミナルで読みやすいよう、本文の各行を約72文字で折り返すことを推奨します。

フッター

フッターには、課題への参照、レビューへの謝辞、破壊的変更の注記など、ツールが説明文を読まずに抽出できる機械可読なトレーラーを記載します。

• 空白を含められるトークンは BREAKING CHANGE のみです。ハイフンでつないだ BREAKING-CHANGE も同義であり、同様に有効です。

ガイドライン：

• 本文の後（本文を省略した場合は説明の後）に空行を一つ挟み、1つ以上のフッターを記載してもかまいません。
• 各フッターは、単語トークンの後に : （コロンと空白）または #（空白とシャープ）を続け、その後に値を記述する必要があります。トークン内の空白は - に置き換える必要があります（例：Reviewed-by:、Acked-by:、Co-authored-by:、Refs: #123、Closes: #45）。
• フッターの値には、空白や改行を含めてもかまいません。次の有効なフッタートークンが解析された時点で、その値は終了します。

破壊的変更

破壊的変更は、次の 2 つの方法のうち少なくとも 1 つで示す必要があります（両方を併用してもかまいません）。

1. 型／スコープのプレフィックスの後に ! を付ける。例：feat(api)!: drop support for Node 18。! を使用する場合、BREAKING CHANGE: フッターは省略してもかまいません。説明自体が破壊的変更の注記として機能します。
2. BREAKING CHANGE: フッター（大文字で記述する必要があります）。例：

   BREAKING CHANGE: `extends` key in config file is now used for extending other config files
   

ガイドライン：

• 型が feat、fix、その他のいずれであるかにかかわらず、破壊的変更は SemVer の MAJOR バンプに必ず対応させてください。
• BREAKING CHANGE は必ず大文字で記述してください。その他の Conventional Commits のトークンは、解析時には大文字と小文字が区別されませんが、小文字で記述することを推奨します。

SemVer との対応関係

SemVer との対応関係では、Conventional Commit の各形式が示すリリースバンプを定めます。コミットのヘッダータイプと破壊的変更マーカーを選ぶ際は、この表を使用してください。

コミット形式	SemVer のバンプ
fix: ...	PATCH
feat: ...	MINOR
! または BREAKING CHANGE: フッターを含む任意の型	MAJOR
! を含まない chore、docs、style、refactor、test、build、ci、perf、revert	リリースバンプなし

ガイドライン：

• コミットに破壊的変更のマークも付いていない限り、fix は PATCH、feat は MINOR として扱ってください。
• ! マーカーまたは BREAKING CHANGE: フッターは、必ず MAJOR として扱ってください。
• 破壊的変更マーカーが付いていない限り、feat／fix 以外の型からリリースバンプを示唆してはいけません。

例

次の例では、スコープ、本文、フッター、破壊的変更、リバートを含む、一般的なケースで使用できるコミット形式を示します。

スコープなし、本文なしのシンプルな例：

docs: correct spelling of CHANGELOG

スコープあり：

feat(lang): add Polish language

! による破壊的変更：

feat!: send an email to the customer when a product is shipped

スコープ付きで ! による破壊的変更：

feat(api)!: drop support for Node 18

フッターによる破壊的変更（! なし）：

feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

本文と複数のフッターあり：

fix: prevent racing of requests

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

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

Reviewed-by: Z
Refs: #123

リバート：

revert: feat(lang): add Polish language

Refs: 676104e, a215868

ガイドライン：

• 新しいコミットメッセージは、最も近い適切な例に倣うことを推奨します。
• コミットにヘッダー行以外が含まれる場合、ヘッダー、本文、フッターの間の空行による区切りを必ず維持してください。

ツールに関する注意事項

プロジェクトにコミットフックや、不正な形式のメッセージを拒否する CI チェックが導入されていない場合、作成者が気づかない限り、形式に準拠していないコミットはそのまま取り込まれます。この確認を機械的に行うため、このスキルには scripts/check-commit-message.mjs が含まれています。これは依存関係が軽量な（標準ライブラリのみを使用する）Node バリデーターで、ヘッダーを上記のルールに照らして検証し、すべての違反を報告します。ファイル引数または標準入力からメッセージを読み込みます。

例：

# Paths are relative to this skill's installed directory — from a message
# file, or piped on stdin:
node scripts/check-commit-message.mjs .git/COMMIT_EDITMSG
printf 'feat(lang): add Polish language' | node scripts/check-commit-message.mjs

• コミットを修正または履歴を書き換える場合は、書き換えたすべてのコミットが引き続き準拠していることを再確認してください。特に、破壊的変更に ! またはフッターのいずれかが付いていることを確認してください。

ガイドライン：

• プロジェクトでコミットフックまたは CI チェックによるコミットメッセージの強制が行われていない場合は、この形式を必ず自分で遵守してください。
• コミット前に、目視で確認するのではなく、ヘッダー（および同じ形式に従うプルリクエストのタイトル）に対して check-commit-message.mjs を実行することを推奨します。
• 終了コード 1 は修正すべき不正なヘッダー、終了コード 2 は不正な呼び出し（メッセージが指定されていない）として扱ってください。終了コード 0 はヘッダーが準拠していることを意味します。