conventional-commits

Conventional Commits

このスキルでは、Conventional Commits 仕様（v1.0.0）に準拠した Git コミットの作成方法について説明します。

目的

Conventional Commits は、コミットメッセージに人間と機械の両方が読み取れる意味を付与するための仕様です。明確なコミット履歴を作成するための簡単なルールを提供し、プロジェクトの変更内容を理解しやすくして、コラボレーションを向上させます。

このスキルを使う場面

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

• Git コミットを作成するとき
• PR のコミットメッセージをレビューするとき
• 明確で構造化されたコミットメッセージを作成するとき
• 複数のコントリビューターが参加するプロジェクトで協力するとき

コミットメッセージの構造

基本形式

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

例

feat: add user authentication
feat(api): add JWT token generation
fix: resolve memory leak in image processor
docs: update README with setup instructions
refactor(database): optimize user query performance

コミットの種類

主な種類

feat - ユーザー向けの新機能

feat: add export to PDF functionality
feat(api): add webhook signature verification

fix - ユーザー向けのバグ修正

fix: resolve login redirect loop
fix(api): handle null response from GitHub webhook

docs - ドキュメントのみの変更

docs: update API endpoint documentation
docs(readme): add troubleshooting section

style - コードの意味に影響しない変更（フォーマット、空白など）

style: format code with StandardRB
style(css): update button padding

refactor - バグ修正でも機能追加でもないコードの変更

refactor: extract user validation to service object
refactor(models): simplify tenant scoping logic

perf - パフォーマンスの改善

perf: add database index for user lookups
perf(queries): reduce N+1 queries in artifacts index

test - テストの追加または更新

test: add specs for user authentication
test(integration): add webhook processing tests

chore - ビルドプロセス、依存関係、保守に関する変更

chore: update Rails to 7.2.0
chore(deps): bump sidekiq from 7.1.0 to 7.2.0

その他の種類（使用頻度は低め）

build - ビルドシステムまたは依存関係の変更

build: configure Docker for production
build(webpack): update asset compilation settings

ci - CI 設定の変更

ci: add security scanning to GitHub Actions
ci(tests): run RSpec in parallel

revert - 以前のコミットを取り消す変更

revert: revert "feat: add export feature"

This reverts commit abc123.

スコープ（任意）

スコープは、コードベースのどの部分が変更されたかについて、追加のコンテキストを示します。

feat(auth): add two-factor authentication
fix(api): handle rate limit errors
docs(contributing): update PR guidelines
refactor(services): extract common validation logic

一般的なスコープの例：

• auth - 認証／認可
• api - API エンドポイント
• ui - ユーザーインターフェースのコンポーネント
• database または db - データベースのモデル／マイグレーション
• services - サービスオブジェクト
• jobs - バックグラウンドジョブ
• tests - テストスイート
• deps - 依存関係
• config - 設定の変更
• docs - ドキュメント

プロジェクトのアーキテクチャやドメイン領域に合ったスコープを選んでください。

説明

説明は、コードの変更を簡潔にまとめたものです。

ルール：

• 命令形の現在形を使います。「added」や「adds」ではなく「add」とします
• 先頭の文字を大文字にしません
• 末尾にピリオド（.）を付けません
• 72 文字以内にします（できれば 50 文字以内）

良い説明：

add user profile page
fix memory leak in file upload
update email templates for notifications
remove deprecated API endpoint

悪い説明：

Added user profile page          # Past tense
Fix Memory Leak In File Upload   # Capitalized
Updated email templates.          # Period at end
Lots of changes to the codebase   # Vague

本文（任意）

本文では、変更について追加のコンテキストを説明します。

本文を含める場合：

• 説明が必要な複雑な変更
• 一見して分かりにくい設計上の判断
• 破壊的変更
• 移行手順

形式：

• 説明との間に空行を入れます
• 説明と同様に命令形を使います
• 72 文字で折り返します
• 複数の段落を含めることができます

例：

feat(api): add webhook signature verification

Add HMAC-SHA256 signature verification for all incoming webhooks
to prevent unauthorized access and replay attacks.

The signature is validated using a secret key stored per
installation. Requests with invalid signatures are rejected
with a 401 response.

フッター（任意）

フッターでは、コミットのメタデータを指定します。

破壊的変更

互換性のない API 変更には、BREAKING CHANGE: フッターを使用します。

feat(api): change authentication endpoint

BREAKING CHANGE: The /auth endpoint now requires a client_id parameter.
Update all API clients to include client_id in authentication requests.

または、種類／スコープの後に ! を付けます。

feat!: change authentication endpoint
feat(api)!: remove deprecated /login endpoint

イシューの参照

イシューやプルリクエストを参照します。

fix(auth): resolve session timeout bug

Fixes #123
Closes #456
Related to #789

一般的な参照の種類：

• Fixes #123 - イシューをクローズします
• Closes #123 - イシューをクローズします
• Resolves #123 - イシューをクローズします
• Related to #123 - クローズせずに参照します
• See also #123 - 追加の参照です

共著者

複数のコントリビューターをクレジットします。

feat: add data export feature

Co-authored-by: Jane Doe <[email protected]>
Co-authored-by: John Smith <[email protected]>

例の全体

シンプルな機能

feat: add password reset functionality

スコープ付きの機能

feat(api): add rate limiting for endpoints

本文付きのバグ修正

fix(api): handle rate limit errors from GitHub

When GitHub API returns 429 status, retry the request
with exponential backoff up to 3 attempts before failing.

Fixes #234

破壊的変更

feat(api)!: redesign webhook payload structure

BREAKING CHANGE: Webhook payloads now use a nested structure.

Before:
{
  "event": "issue.created",
  "data": {...}
}

After:
{
  "type": "issue",
  "action": "created",
  "payload": {...}
}

Clients must update their webhook handlers to use the new structure.

リファクタリング

refactor(services): extract validation to concern

Move common validation logic from multiple services into
a shared ValidationConcern module. No behavior changes.

複数のフッター

fix(auth): resolve concurrent login race condition

Add database-level locking to prevent race condition when
multiple login attempts occur simultaneously for the same user.

Fixes #567
Related to #432
Reviewed-by: Jane Doe <[email protected]>

ベストプラクティス

推奨事項：

✅ 現在形の命令形を使います（「added」ではなく「add」） ✅ できる限り、1 行目を 50 文字以内にします ✅ フッターでイシュー／PR を参照します ✅ 本文では「何を」ではなく「なぜ」を説明します（何を変更したかはコードを見れば分かります） ✅ 大きな変更は複数のコミットに分割します ✅ コミットをアトミックにします（1 つのコミットにつき、論理的な変更を 1 つ）

避けること：

❌ 曖昧な説明を使う（「いろいろ修正」「更新」など） ❌ 関連のない複数の変更を1つのコミットにまとめる ❌ 説明の最初の文字を大文字にする ❌ 説明の末尾にピリオドを付ける ❌ 過去形を使う（「追加した」「修正した」など） ❌ 動作しないコードをコミットする（各コミットは動作する必要があります）

概要

Conventional Commits には次の利点があります：

• ✅ 明確で一貫性のあるコミット履歴
• ✅ 意図を明示することで、コラボレーションが向上
• ✅ コードレビューとGit履歴の確認が容易
• ✅ 構造化されたメッセージによって、プロジェクトのドキュメントが改善

基本の形式：

<type>(<scope>): <description>

[body]

[footer]

詳細な例や特殊なケースについては、references/commit-examples.md を参照してください。