conventional-commits

Conventional Commits

コミット、ブランチ、PR、Issue には、必ず Conventional Commits 1.0.0 仕様に厳密に従った名前を付けます。何よりも優先するルールは 2 つあります。各コミットはアトミック（1 つの論理的な変更のみ）であること、そしてコミットが反映される前に、メッセージを仕様と実際の差分に照らして検証することです。

例外 — ツールが生成したデフォルトのメッセージはそのままにします。 マージなどによって自動生成されたコミットは、デフォルトのメッセージ（Merge branch ...、Merge pull request ...、Revert ...）を維持し、Conventional Commits 形式のサブジェクトに書き換えないでください。多くのツールはデフォルトのプレフィックスでこれらを識別してフィルタリングするため、プレフィックスをそのまま維持する必要があります。

形式

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

[optional body]

[optional footer(s)]

タイプ — 差分が 実際に行うこと に合致するものを選びます。

type	用途	SemVer
feat	新機能	MINOR
fix	バグ修正	PATCH
docs	ドキュメントのみ	—
style	空白、書式、セミコロン。CSS や視覚的な変更は含みません	—
refactor	バグ修正でも機能追加でもないコード変更	—
perf	パフォーマンス改善	—
test	テストの追加または修正	—
build	ビルドシステムまたは依存関係	—
ci	CI の設定	—
chore	本番コードに影響しないその他の変更	—
wayfinder	wayfinder マップのチケット／Issue	—
spec	仕様書（例：/to-spec を使って wayfinder マップから作成したもの）	—

CSS、Tailwind クラス、その他の視覚的な変更はコードであり、style ではありません。新しい見た目には feat、視覚的なバグには fix、見た目を変えずにスタイルを再構成する場合は refactor を使います。

wayfinder マップのチケット／Issue には必ず wayfinder を使い、仕様書には必ず spec を使います。変更自体が何を行うか（feat、fix など）ではなく、成果物によってタイプが決まります。

サブジェクト行のルール：

• type は必須です。上の表にある小文字のタイプを使います。
• scope は任意です。影響を受けるセクションを示す名詞を括弧で囲みます — fix(parser):。
• コロンの直前の ! は破壊的変更（MAJOR）を示します — feat(api)!:。
• コロンとその後のスペースは、それぞれ 1 つだけにします。その後に説明を続けます。
• description：タイプと同じ行に記述する、簡潔な命令形の要約です。変更の本質を先に述べます。タイプにすでに動詞の意味が含まれるため、それを繰り返すだけの先頭の動詞（feat: add…、fix: fix…）や、単に文を長くする動詞（give…、make…、update…）は省きます。タイプだけでは示せない変更の_方法_を表す場合に限り、動詞を残します（refactor(auth): extract token parser）。
  • feat(time-tracking): add shift-derived automatic blocking → feat(time-tracking): shift-derived automatic blocking
  • refactor(seeder): give duty-plan departments unique shifts → refactor(seeder): unique shifts per duty-plan department

本文とフッター（変更内容に必要な場合のみ）：

• 本文：説明の後に空行を 1 行挿入し、その後に自由形式の段落を続けます。
• フッター：本文の後に空行を 1 行挿入します。各フッターは Token: value または Token #value の形式です。BREAKING CHANGE を除き、Token 内のスペースは - に置き換えます（例：Reviewed-by、Refs）。
• 破壊的変更：プレフィックスに ! を付けるか、フッターに BREAKING CHANGE: <description> を記述します。Token は大文字でなければなりません（BREAKING-CHANGE も同義です）。

言語：

• 常にアメリカ英語を使います。

よく使うプリセット

差分が該当する場合は、これらの定型メッセージを使ってください。繰り返し発生するコミットの一貫性を保てます。

• style: lint — コミット内容がリンティング／フォーマットの変更のみである場合（コードの意味に変更がない場合）。
• build(deps): upgrade deps — 複数のパッケージにまたがる広範な依存関係の更新。
• build(deps): upgrade <package> — 例：build(deps): upgrade vitest のように、単一のパッケージに限定した依存関係の更新。

プリセットを適用するのは、ステージ済みの差分が実際にその変更のみである場合に限ります。それ以外の変更が含まれている場合は、プリセットを無理に当てはめず、以下のステップ 2 のように切り分けてください。

コミットの作成

1. 差分全体を確認します。 git status と git diff（ステージ済みと未ステージの両方）を実行します。作業を始める前に、すべてのハンクの内容を把握してください。

2. アトミックなコミットに分割します。 各コミットが単一の種別＋スコープ＋意図となるよう、ハンクをまとめます。機能、修正、リファクタリング、または無関係なスコープが混在する差分はアトミックではありません。単位ごとに 1 つのコミットを計画してください。すべてのハンクがそれぞれ 1 つの計画済みコミットに割り当てられ、各コミットが 1 つの種別／スコープ／意図になったら完了です。

3. 一度に 1 つずつステージして下書きを作成します。 そのコミットのハンクのみをステージし（git add <paths>、またはファイルの一部だけを対象とする場合は git add -p）、上記の形式でメッセージの下書きを作成します。

4. コミット前に、以下の 検証 を行います。すべてのチェックに合格するまで git commit を実行しないでください。

5. 検証済みのメッセージで コミット し、次の計画済みコミットについてステップ 3 に戻ります。

検証

フィードバックを確認する手順です。下書きのメッセージを仕様と ステージ済み の差分の両方に照らして読み直します。すべての項目に合格する必要があります。1 つでも不合格の場合は、メッセージを修正する（またはコミットを再分割する）うえで、チェックリストをもう一度実行してください。

• 形式：<type>[scope][!]: <description> に一致していること（表に記載された小文字の種別、コロン 1 つ＋半角スペース 1 つ）。
• 種別が実際の変更内容と一致していること：種別はステージ済みの差分の内容を表している必要があります。リファクタリングに feat を使ったり、新しい機能に fix を使ったり、CSS や UI の変更に style を使ったりしないでください。
• アトミックであること：ステージ済みの差分が 1 つの論理的な変更であり、無関係な変更が含まれていないこと。
• 説明：命令形で簡潔かつ変更内容を正確に表し、内容を先に述べていること。種別を繰り返すだけ、または字数を埋めるだけの動詞で始めないでください。
• 本文／フッター（ある場合）：空行で区切られていること。フッタートークンの形式が正しいこと。破壊的変更には ! または大文字の BREAKING CHANGE: フッターが付いていること。
• 著者情報：帰属フッターが、以下の「著者情報」セクションで指定されているものと正確に一致し、その後に何も続かないこと。

ブランチ、PR、Issue

同じ type の語彙と件名のルールが適用され、同じ方法で検証します。

• ブランチ：<type>/<kebab-case-summary> — feat/user-export、fix/parser-crash。
• PR タイトル：Conventional Commits の件名行（<type>[scope][!]: <description>）と完全に一致させます。これは squash merge のコミットになるためです。
• Issue タイトル：望ましい変更またはバグを表す <type>[scope]: <description>。

著者情報

ハーネスまたはユーザーの指示で指定された帰属フッターを、正確に追加してください。

コミットメッセージのフォーマット

シェルからコミットする場合は、各段落を個別の -m 引数として渡してください。通常の引用符で囲まれた \n は、そのまま文字列として扱われます。

git commit \
  -m 'type(scope): summary' \
  -m 'Body paragraph.' \
  -m 'Closes #123'

正確なフォーマットにするには、実際の改行を含む git commit -F <message-file> を使用してください。

プッシュする前に、次を確認してください。

git show -s --format=%B HEAD | sed -n l

完了条件：意図した各行が個別に表示され、文字列としての \n が含まれていないこと。