conventional-commits

Conventional Commits

標準化されたセマンティックなコミットメッセージを記述し、自動的なバージョン管理と変更履歴の生成を可能にします。

基本的なワークフロー

1. 変更を分析する：ステージングされたファイルと変更内容を確認します
2. 種類を決定する：適切なコミットの種類（feat、fix など）を選択します
3. スコープを特定する：影響を受けるコンポーネントやモジュールを指定します（任意）
4. 説明を記述する：命令形で簡潔に要約します
5. 本文を追加する：詳細な説明を任意で追加します
6. フッターを含める：破壊的変更や課題への参照を記載します

コミットメッセージの形式

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

コミットの種類

種類	説明	Semver	例
feat	新機能	MINOR	feat: add user authentication
fix	バグ修正	PATCH	fix: resolve login redirect loop
docs	ドキュメントのみ	-	docs: update API reference
style	書式、空白	-	style: fix indentation in utils
refactor	機能追加やバグ修正を伴わないコード変更	-	refactor: extract validation logic
perf	パフォーマンスの改善	PATCH	perf: optimize database queries
test	テストの追加や修正	-	test: add unit tests for auth
build	ビルドシステム、依存関係	-	build: upgrade to Node 20
ci	CI/CD の設定	-	ci: add GitHub Actions workflow
chore	メンテナンスタスク	-	chore: update .gitignore
revert	以前のコミットを取り消す	-	revert: undo feature flag change

スコープ

スコープは、コードベースのどの領域が影響を受けるかを示します。

# Component/module scopes
feat(auth): add OAuth2 support
fix(api): handle timeout errors
docs(readme): add installation steps

# File-based scopes
style(eslint): update linting rules
build(docker): optimize image size

# Layer scopes
refactor(service): extract user service
test(e2e): add checkout flow tests

破壊的変更

破壊的変更には ! または BREAKING CHANGE フッターを付けます。

# Using ! notation
feat(api)!: change response format to JSON:API

# Using footer
feat(api): change response format

BREAKING CHANGE: Response now follows JSON:API specification.
Clients must update their parsers.

コミットメッセージの例

シンプルな機能追加

feat: add dark mode toggle

スコープ付きの機能追加

feat(ui): add dark mode toggle to settings page

課題への参照付きのバグ修正

fix(auth): resolve session expiration race condition

The session refresh was racing with the expiration check,
causing intermittent logouts.

Fixes #234

破壊的変更

feat(api)!: migrate to v2 response format

BREAKING CHANGE: All API responses now use camelCase keys
instead of snake_case. Update client parsers accordingly.

Migration guide: https://docs.example.com/v2-migration

複数のフッター

fix(payments): correct tax calculation for EU customers

Updated tax calculation to use customer's billing country
instead of shipping country for digital goods.

Fixes #456
Reviewed-by: Alice
Co-authored-by: Bob <[email protected]>

コミットの取り消し

revert: feat(auth): add OAuth2 support

This reverts commit abc123def456.

Reason: OAuth provider has rate limiting issues in production.
Will re-implement with proper caching.

説明のガイドライン

すること

• 命令形を使います：「added」や「adds」ではなく「add」
• 72 文字以内に収めます
• 小文字で始めます
• 末尾にピリオドを付けません
• 具体的かつ簡潔にします

しないこと

• 「Fixed bug」（曖昧すぎます）
• 「Updated stuff」（説明になっていません）
• 「WIP」（準備ができてからコミットします）
• 「misc changes」（個別のコミットに分けます）

良い例

feat: add email verification flow
fix: prevent duplicate form submissions
refactor: extract payment processing to service
perf: cache user preferences in memory
docs: add API authentication examples

悪い例

# Too vague
fix: fixed it
update: updates

# Wrong tense
feat: added new feature
fix: fixes the bug

# Too long
feat: add a new feature that allows users to export their data in multiple formats including CSV, JSON, and XML

本文のガイドライン

本文を含める場合：

• 変更の背景や説明が必要な場合
• 複雑なロジックが自明ではない場合
• 破壊的変更に移行情報が必要な場合
• 関連する複数の変更を1つのコミットにまとめる場合

fix(cache): invalidate user cache on profile update

Previously, profile updates were not reflected until cache expiry.
This caused confusion when users updated their avatar and didn't
see the change immediately.

The fix adds cache invalidation after successful profile updates
and ensures CDN purge for static assets.

フッタートークン

トークン	用途	例
Fixes	課題を解決する	Fixes #123
Closes	課題を解決する	Closes #456
Refs	課題を参照する	Refs #789
BREAKING CHANGE	破壊的変更	BREAKING CHANGE: description
Reviewed-by	レビュアーのクレジット	Reviewed-by: Name
Co-authored-by	共同作成者のクレジット	Co-authored-by: Name <email>

ツールとの連携

Commitlint の設定

// commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      [
        'feat', 'fix', 'docs', 'style', 'refactor',
        'perf', 'test', 'build', 'ci', 'chore', 'revert'
      ]
    ],
    'scope-case': [2, 'always', 'kebab-case'],
    'subject-case': [2, 'always', 'lower-case'],
    'subject-max-length': [2, 'always', 72],
    'body-max-line-length': [2, 'always', 100]
  }
};

Husky のコミット前フック

# .husky/commit-msg
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"
npx --no-install commitlint --edit "$1"

Package.json の設定

{
  "devDependencies": {
    "@commitlint/cli": "^18.0.0",
    "@commitlint/config-conventional": "^18.0.0",
    "husky": "^8.0.0"
  },
  "scripts": {
    "prepare": "husky install"
  }
}

Semantic Release との連携

Conventional Commits を使うと、バージョン管理を自動化できます。

# .releaserc.yml
branches:
  - main
plugins:
  - "@semantic-release/commit-analyzer"
  - "@semantic-release/release-notes-generator"
  - "@semantic-release/changelog"
  - "@semantic-release/npm"
  - "@semantic-release/git"

バージョン更新のルール

コミットの種類	バージョン更新	例
feat	マイナー（0.X.0）	1.2.0 → 1.3.0
fix	パッチ（0.0.X）	1.2.0 → 1.2.1
perf	パッチ（0.0.X）	1.2.0 → 1.2.1
BREAKING CHANGE	メジャー（X.0.0）	1.2.0 → 2.0.0
その他	更新なし	1.2.0 → 1.2.0

コミットメッセージの生成

変更を分析したら、コミットメッセージを生成します。

# 1. Check staged changes
git diff --cached --name-only

# 2. Analyze change type
# - New files = likely feat
# - Modified test files = test
# - Modified docs = docs
# - Bug-related keywords = fix

# 3. Identify scope from path
# src/components/Button.tsx → components or ui
# src/services/auth.ts → auth or services

# 4. Generate message
feat(ui): add loading state to Button component

ベストプラクティス

1. 1つのコミットにつき、論理的な変更は1つ：機能追加とバグ修正を混在させないでください
2. 早めに、こまめにコミットする：小さく、対象を絞ったコミットにします
3. レビュアー向けに記述する：何をしたかだけでなく、なぜ行ったかを説明します
4. 課題を参照する：該当する場合はチケットや課題へのリンクを含めます
5. スコープを一貫して使う：チーム内の規約を定めます
6. コミット前に確認する：git diff --cached で変更を確認します

出力チェックリスト

すべてのコミットメッセージは、次の条件を満たす必要があります。

• 有効なタイプ（feat、fix、docs など）で始める
• 説明文を命令形にする
• 説明文を72文字未満にする
• 該当する場合はスコープを含める
• 破壊的変更には ! またはフッターで印を付ける
• フッターで関連するイシューを参照する
• 複雑な変更には本文を記載する
• チームのスコープ規約に従う