conventional-commits

Conventional Commits

構造化されたコミット履歴、自動的な変更履歴の生成、セマンティックバージョニングのために、Conventional Commits v1.0.0 仕様に従ってコミットメッセージを作成します。

このスキルを使用する場面

以下の場合にこのスキルを使用します。

• 構造化されたプロジェクトの Git コミットメッセージを作成するとき
• Conventional Commits 仕様に照らしてコミットメッセージの形式を検証するとき
• commitlint によるコミットメッセージの検証を設定するとき
• コミット履歴から変更履歴を生成する設定を行うとき
• セマンティックバージョニングの自動化を実装するとき
• 仕様への準拠状況についてコミットメッセージをレビューするとき
• チームにコミットメッセージの基準を周知するとき
• semantic-release、commitizen、git-cliff などのツールと連携するとき

メッセージの構造

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

構成要素

構成要素	必須	説明	例
type	はい	コミットのカテゴリ	feat、fix、docs
scope	いいえ	影響を受けるコードベースの領域	(auth)、(parser)
description	はい	変更の簡潔な要約	add user authentication
body	いいえ	詳細な説明	背景を含む複数の段落
footer	いいえ	破壊的変更、課題への参照	BREAKING CHANGE:、Refs: #123

コミットタイプ

必須タイプ（SemVer への影響）

これらのタイプは Conventional Commits 仕様で必須とされており、セマンティックバージョニングに直接影響します。

flowchart LR
    Fix[fix: Bug fix<br/>for users] --> PatchVer[PATCH<br/>0.0.X]
    Feat[feat: New feature<br/>for users] --> MinorVer[MINOR<br/>0.X.0]
    Breaking[Any type with<br/>BREAKING CHANGE or !] --> MajorVer[MAJOR<br/>X.0.0]

    style PatchVer fill:#e1f5ff
    style MinorVer fill:#fff4e1
    style MajorVer fill:#ffe1e1

タイプ	説明	SemVer	例
feat	ユーザー向けの新機能	MINOR (0.X.0)	feat: add user authentication
fix	ユーザー向けのバグ修正	PATCH (0.0.X)	fix: prevent crash on empty input

推奨タイプ（Angular 規約）

これらのタイプは、Angular のコミットガイドラインに基づく@commitlint/config-conventionalのものです。BREAKING CHANGE を含まない限り、SemVer に暗黙的な影響はありません。

タイプ	説明	例
build	ビルドシステムまたは外部依存関係の変更	build: update webpack to v5
ci	CI 設定の変更	ci: add Node 18 to test matrix
docs	ドキュメントのみの変更	docs: update API reference
perf	パフォーマンスの改善	perf: reduce bundle size by 20%
refactor	バグ修正や機能追加を伴わないコードの変更	refactor: extract validation logic
style	コードスタイルの変更（空白、フォーマット）	style: fix indentation
test	テストの追加または修正	test: add unit tests for parser

その他の一般的なタイプ

タイプ	説明	例
chore	src ファイルや test ファイルを変更しない変更	chore: update .gitignore
revert	以前のコミットを取り消す	revert: feat: add user auth

注：チームは feat と fix 以外の独自のタイプを定義できますが、Angular 規約のタイプは多くのツールで広くサポートされています。

仕様のルール

以下のルールは、RFC 2119に基づく、Conventional Commits 1.0.0 の公式仕様です。

種類とスコープ

1. コミットには、名詞（feat、fix など）からなる種類を接頭辞として付ける必要があります。その後にスコープを任意で指定し、! を任意で付け、末尾にコロンとスペースを必ず付けます。

2. コミットで新機能を追加する場合は、種類に feat を使用する必要があります。

3. コミットがバグ修正にあたる場合は、種類に fix を使用する必要があります。

4. 種類の後にスコープを指定できます。スコープは、コードベース内のセクションを表す名詞を丸括弧で囲んだものにする必要があります。例：fix(parser):

5. 説明は、種類／スコープの接頭辞の後のコロンとスペースに続けて、直ちに記述する必要があります。説明はコードの変更を短く要約したものです。例：fix: array parsing issue when multiple spaces were contained in string

本文

6. 短い説明の後に、追加の背景情報を記載する長めのコミット本文を追加できます。本文は説明の後に空行を1行挟んで始める必要があります。

7. コミット本文は自由形式で、改行で区切られた段落をいくつでも含めることができます。

フッター

8. 本文の後に空行を1行挟んで、フッターを1つ以上追加できます。各フッターは、単語トークンに続けて :<space> または <space># の区切りを置き、その後に文字列値を記述する必要があります（git trailer の慣例に基づいています）。

9. フッターのトークンでは、空白文字の代わりに - を使用する必要があります。例：Acked-by（これにより、フッターセクションと複数段落の本文を区別しやすくなります）。例外として、BREAKING CHANGE もトークンとして使用できます。

10. フッターの値には、スペースや改行を含めることができます。次に有効なフッタートークンと区切りの組み合わせが現れた時点で、解析を終了する必要があります。

破壊的変更

11. 破壊的変更は、コミットの種類／スコープの接頭辞、またはフッターの項目として示す必要があります。

12. フッターとして記載する場合、破壊的変更は大文字の BREAKING CHANGE に続けてコロン、スペース、説明を記述する必要があります。例：BREAKING CHANGE: environment variables now take precedence over config files

13. 種類／スコープの接頭辞に含める場合、破壊的変更は : の直前に ! を付けて示す必要があります。! を使用する場合、フッターの BREAKING CHANGE: は省略できます。コミットの説明で破壊的変更の内容を説明するものとします。

追加ルール

14. コミットメッセージには、feat と fix 以外の種類も使用できます。例：docs: update ref docs

15. 実装者は、BREAKING CHANGE を除き、Conventional Commits を構成する情報単位を大文字と小文字を区別せずに扱う必要があります。BREAKING CHANGE は大文字で記述する必要があります。

16. BREAKING-CHANGE は、フッターのトークンとして使用する場合、BREAKING CHANGE と同義である必要があります。

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

Angular のコミットメッセージガイドラインに基づきます。

要約／説明のガイドライン

• 命令形かつ現在形を使用します。「changed」や「changes」ではなく「change」を使用します
• 先頭の文字を大文字にしません
• 末尾にピリオド（.）を付けません
• ヘッダー全体（種類 + スコープ + 説明）を72文字未満にします

良い例

feat: add validation for email input
fix: handle null pointer in user service
docs: update installation instructions
refactor: simplify authentication flow

悪い例（避けてください）

feat: Added validation for email input     # Past tense
fix: Handles null pointer in user service  # Third person
docs: Update installation instructions.    # Period at end, capitalized
FEAT: add validation                       # Uppercase type (inconsistent)

本文のガイドライン

• 命令形かつ現在形を使用します（要約と同じです）
• 変更の動機を説明します
• 参考になる場合は、変更前と変更後の動作を比較します
• 本文は説明の後に空行を1行挟んで始める必要があります
• 推奨される最小文字数：本文を記載する場合は20文字

破壊的変更

破壊的変更を示す方法

同等の方法が3つあります。

1. フッター表記：

   feat: allow provided config object to extend other configs
   
   BREAKING CHANGE: `extends` key in config file is now used for extending other config files
   

2. 種類の末尾に ! を付ける：

   feat!: remove support for Node 6
   

3. 種類 + スコープの末尾に ! を付ける：

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

ルール

• BREAKING CHANGE は大文字で記述する必要があります
• フッタートークンとして使用する場合、BREAKING-CHANGE は同義です
• 破壊的変更は、SemVer の MAJOR バージョンの引き上げに対応させる必要があります

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

flowchart TD
    Start([Analyze Commits]) --> CheckBreaking{Any commit has<br/>BREAKING CHANGE<br/>or !?}
    CheckBreaking -->|Yes| Major[MAJOR bump<br/>X.0.0]
    CheckBreaking -->|No| CheckFeat{Any commit<br/>is feat?}
    CheckFeat -->|Yes| Minor[MINOR bump<br/>0.X.0]
    CheckFeat -->|No| CheckFix{Any commit<br/>is fix?}
    CheckFix -->|Yes| Patch[PATCH bump<br/>0.0.X]
    CheckFix -->|No| NoChange[No version change]

    Major --> End([Release])
    Minor --> End
    Patch --> End
    NoChange --> End

コミットタイプとバージョンの対応

コミットタイプ	バージョンの更新
fix	PATCH（0.0.X）
feat	MINOR（0.X.0）
BREAKING CHANGE or !	MAJOR（X.0.0）

理由：コミット履歴に基づくセマンティックバージョニングの自動化を可能にします。

検証パターン

ヘッダー検証用正規表現

^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?!?:\s.+$

Python による検証例

import re

CONVENTIONAL_COMMIT_PATTERN = re.compile(
    r"^(?P<type>feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)"
    r"(?:\((?P<scope>[^)]+)\))?"
    r"(?P<breaking>!)?"
    r":\s"
    r"(?P<description>.+)$"
)


def validate_header(header: str) -> bool:
    """Validate commit header follows Conventional Commits."""
    return bool(CONVENTIONAL_COMMIT_PATTERN.match(header))


def parse_header(header: str) -> dict | None:
    """Parse commit header into components."""
    match = CONVENTIONAL_COMMIT_PATTERN.match(header)
    if not match:
        return None
    return {
        "type": match.group("type"),
        "scope": match.group("scope"),
        "breaking": bool(match.group("breaking")),
        "description": match.group("description"),
    }

完全な例

シンプルなコミット

feat: add user authentication

fix: prevent crash on empty input

docs: correct spelling of CHANGELOG

スコープ付きコミット

feat(lang): add Polish language

feat(parser): add ability to parse arrays

fix(auth): handle token expiration correctly

破壊的変更

feat: allow provided config object to extend other configs

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

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

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

chore!: drop support for Node 6

BREAKING CHANGE: use JavaScript features not available in Node 6.

フッター付きの複数段落の本文

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.

Reviewed-by: Z
Refs: #123

リバートコミット

revert: let us never again speak of the noodle incident

Refs: 676104e, a215868

パフォーマンスの改善

perf: reduce memory allocation in parser by 40%

Replace string concatenation with StringBuilder pattern.
Benchmark results show 40% reduction in heap allocations.

Refs: #456

リファクタリング

refactor: extract authentication logic into separate module

Move auth-related functions from utils.py to auth.py.
No functional changes.

ビルド／CI の変更

ci: add Node 18 to test matrix

build: upgrade webpack from v4 to v5

- Update webpack.config.js for v5 compatibility
- Replace deprecated plugins
- Update all loader dependencies

Refs: #789

テストとスタイルの変更

test: add unit tests for user validation

Cover edge cases for email validation and password strength.

style: format code according to prettier config

chore: update .gitignore to exclude IDE files

検証ツールとの統合

commitlint の設定

Angular 設定を使用して、commitlint でコミットを検証します。

# Install commitlint
npm install --save-dev @commitlint/cli @commitlint/config-conventional

# Create configuration
echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js

# Test commit message
echo 'feat(api): add new endpoint' | npx commitlint

commitlint の設定に関する詳しいガイダンスについては、このドキュメントの内容を参照してください。ワークスペースに commitlint プラグインがインストールされている場合は、プロジェクト固有のルールや例について、そのプラグインの案内に従うことができます。

コミット前フック

コミット前フックを使用して、コミットメッセージの形式を適用します。ワークスペースにコミット前プラグインがインストールされている場合は、フックの設定ガイダンスとして利用できます。インストールされていない場合は、フックを直接設定してください。

変更履歴の生成

semantic-release を使用して、Conventional Commits から変更履歴を生成します。

// release.config.js
module.exports = {
  branches: ['main'],
  plugins: [
    '@semantic-release/commit-analyzer',
    '@semantic-release/release-notes-generator',
  ],
};

または、git-cliff を使用します。

# cliff.toml
[git]
conventional_commits = true

メリット

公式仕様より：

1. CHANGELOG の自動生成 - ツールがコミット履歴を解析し、リリースノートを生成します
2. セマンティックバージョンの更新を自動決定 - マージされたコミットのタイプに基づきます
3. 変更内容を伝達 - チームメイト、一般の人々、ステークホルダーに伝えます
4. ビルドおよび公開プロセスを起動 - CI/CD パイプラインが特定のコミットタイプに応じて動作します
5. コントリビュートしやすくする - 構造化されたコミット履歴をたどることで、変更に参加しやすくなります

よくある質問

カスタムタイプを使用できますか？

はい。仕様では feat と fix 以外のタイプは必須ではありませんが、BREAKING CHANGE を含まない限り、SemVer への暗黙的な影響はありません。チームでは wip、deps、security などのタイプを追加することがよくあります。

仕様では大文字と小文字が区別されますか？

実装によって異なります。ほとんどのツールは小文字に正規化します。例外として、BREAKING CHANGE は大文字でなければなりません。ベストプラクティスは、プロジェクト内で一貫性を保つことです。

マージコミットはどうなりますか？

マージコミットは通常、変更履歴生成ツールによって無視されます。形式に従う必要はありません。

誤ったタイプを使用した場合はどうなりますか？

マージ／リリース前：git rebase -i を使用してコミット履歴を編集します。リリース後：ツールやプロセスによって異なります。最悪の場合：仕様に基づくツールで、規約に沿っていないコミットが見落とされます。

すべてのコントリビューターが Conventional Commits を使用する必要がありますか？

いいえ。スカッシュベースのワークフローでは、メンテナーがマージ時にコミットメッセージを整えることができます。多くのチームでは、プルリクエストのコミットを自動的にスカッシュし、適切なコミットメッセージを入力するフォームを表示するように Git システムを設定しています。

リバートコミットはどのように扱えばよいですか？

revert タイプを使用し、フッターでリバート対象のコミット SHA を参照します。

revert: let us never again speak of the noodle incident

Refs: 676104e, a215868

関連するスキル

コミットメッセージの検証と適用：

• commitlint - コミットメッセージの検証に commitlint を設定して使用します。インストール済みの commitlint プラグインが利用できる場合は、プロジェクト固有のルールにそのプラグインを使用してください。利用できない場合は、このドキュメントのガイダンスに従ってください。
• pre-commit - 自動検証のための pre-commit フックを設定します。インストール済みの pre-commit プラグインが利用できる場合は、フックの設定方法についてそのプラグインを使用してください。利用できない場合は、フックを直接設定してください。

Git ワークフローツール：

• commit-staged - 差分からコミットメッセージを生成するオプションのツールです。インストール済みの場合は使用できます。そうでない場合は、差分とこのリファレンスに基づいて Conventional Commit のヘッダーを手動で作成してください。

参考資料

公式ドキュメント

• Conventional Commits v1.0.0 Specification - 公式仕様（2025-01-15 閲覧）
• Conventional Commits GitHub Repository - 仕様のソースリポジトリ
• RFC 2119 - 仕様で使用されるキーワード

関連規格

• Semantic Versioning (SemVer) - Conventional Commits と連携するバージョン管理規格
• Angular Commit Message Guidelines - Conventional Commits の着想元となった規約
• Git Trailer Format - フッター形式の着想元となった規約

ツールと設定

• @commitlint/config-conventional - Commitlint の共有可能な設定
• @commitlint/config-angular - Angular スタイルの commitlint 設定
• semantic-release - バージョン管理と変更履歴の自動化
• git-cliff - 変更履歴ジェネレーター
• commitizen - 対話型コミットメッセージ作成ツール