優れたGitコミットメッセージを作成する：明確な履歴のためのベストプラクティス

Gitコミットメッセージは、コードが壊れたり、動作が変更されたり、リリースの説明が必要なときに、あなたのチームが頼りにするメモです。明確なメッセージは、差分を解析しなくても、何が変更され、なぜ変更されたのかを教えてくれます。

優れたコミットメッセージは派手である必要はありません。有用な件名、重要でない変更に対する十分なコンテキスト、そして数ヶ月後でもチームが読める一貫したスタイルが必要です。

なぜ優れたコミットメッセージが重要なのか？

優れたコミットメッセージは、いくつかの実用的な方法で役立ちます：

• 変更の理解： 特定のコミットが何を導入または変更するのかについて即座にコンテキストを提供し、コードのレビューや過去の決定を思い出す際の時間を節約します。
• デバッグ： バグを追跡する際、明確なコミット履歴により、問題のある変更がいつ、なぜ導入されたかを正確に特定できます。
• コラボレーション： プロジェクトに新しく参加するメンバーや古いコードを再訪するメンバーにとって、適切に書かれたメッセージはプロジェクトの開発の軌跡を理解しやすくします。
• コードレビュー： レビュアーに変更の背後にある意図を提供し、より生産的で焦点を絞ったフィードバックを促進します。
• 自動化ツール： チェンジログジェネレーターやリリースノート作成ツールなど、多くのGitツールは効果的に機能するためにコミットメッセージに依存しています。
• 歴史的記録： コードベースの時間の経過に伴う進化を保存する、一種のドキュメントとして機能します。

優れたGitコミットメッセージの構成

広く認識されているGitコミットメッセージの構造は、シンプルでありながら強力なパターンに従います。簡潔な件名と、それに続くオプションのより詳細な本文です。

件名

件名はコミットメッセージの最初の行です。変更の簡潔で命令形の要約であるべきです。コミットのタイトルと考えてください。

件名の主要なガイドライン：

• 簡潔に保つ： 約50文字が有用な目標であり、厳格な制限ではありません。git log --oneline でスキャンできるように、件名は十分に短く保ちます。
• 命令形を使用する： あたかもコマンドを発行しているかのように、動作を説明する動詞で始めます。例：Fix、Add、Refactor、Update、Remove、Style。
• 最初の単語を大文字にする： 標準的な慣習として、件名の最初の文字を大文字にします。
• ピリオドで終わらせない： 件名はタイトルであり、文ではありません。
• 長いメッセージには git commit -m "message" を使用しない： 短いメモには便利ですが、構造化されていないメッセージにつながる可能性があります。より複雑なメッセージには、引数なしで git commit を使用してエディターを開きます。

適切な件名の例：

• feat: ユーザー認証モジュールを追加
• fix: データ処理における無限ループを解決
• docs: READMEのインストール手順を更新
• refactor: 画像読み込みを簡略化
• chore: 開発依存関係を更新

本文

コミットメッセージの本文は、より多くのコンテキストと詳細を提供する場所です。件名とは空白行で区切られます。このセクションはオプションですが、些細な変更以外には強く推奨されます。

本文の主要なガイドライン：

• 「なぜ」と「どのように」を説明する： 何が変更されたかを説明するだけでなく、なぜ変更が必要だったのか、どのように実装されたのかを説明します。このコミットはどのような問題を解決しますか？以前の動作は何でしたか？新しい動作は何ですか？
• 行を72文字で折り返す： これは、多くのGitツールやターミナルで可読性を向上させる長年の慣習です。
• リストには箇条書きを使用する： 複数の変更やポイントを列挙する必要がある場合は、明確にするために箇条書きを使用します。
• 課題やチケットを参照する： コミットが課題トラッカー（例：GitHub Issues、Jira）に関連する場合は、トレーサビリティのためにチケット番号を含めます。

適切なコミットメッセージの例（件名 + 本文）：

feat: ユーザープロフィールページを実装

このコミットはユーザープロフィールページを導入し、ユーザーが自分の
個人情報を表示および編集できるようにします。

以前は、ユーザーはプロフィール詳細にアクセスしたり変更したりできませんでした。
この変更により、新しいルート（`/profile`）と、APIからユーザーデータを
取得し、名前、メール、経歴などのフィールドを更新するためのフォームを
提供する対応するコンポーネントが追加されます。

関連：#123

一般的なコミットメッセージタイプ（Conventional Commits）

コミットメッセージタイプの規約に従うことで、明確さをさらに高め、自動化ツールを有効にすることができます。Conventional Commits 仕様は、構造化されたアプローチを促進する人気のある標準です。

Conventional Commitsは、変更のタイプを示すためにプレフィックスを使用します：

• feat（機能）： コードベースに新しい機能が導入されます。
• fix（バグ修正）： バグが解決されます。
• docs（ドキュメント）： ドキュメントのみの変更。
• style（フォーマット）： コードの意味に影響を与えない変更（空白、フォーマット、セミコロンの欠落など）。
• refactor（リファクタリング）： バグを修正したり機能を追加したりしないコード変更。
• perf（パフォーマンス）： パフォーマンスを向上させるコード変更。
• test（テストの追加または修正）： テストの追加または修正。
• build（ビルドシステムまたは外部依存関係に影響する変更）： 例：npmスクリプト、webpackなど。
• ci（CI設定ファイルとスクリプトへの変更）： 例：Travis、Circle、BrowserStack、SauceLabsなど。
• chore（メンテナンス作業）： リポジトリのハウスキーピングなど、他のタイプに該当しないタスク。

スコープ（オプション）： 影響を受けるコードベースの部分を示すために、プレフィックスにスコープを追加できます。例：feat(auth): JWT認証を追加。

フッター（オプション）： フッターを使用して、課題を参照したり、破壊的変更をマークしたり、その他のメタデータを追加したりします。Conventional Commitsは、破壊的変更に BREAKING CHANGE: を使用します。

Conventional Commitsを使用した例：

fix(api): ユーザーデータ取得のエンドポイントを修正

以前は、`/users/:id/data` エンドポイントが古い情報を返していました。
このコミットは、エンドポイントを `/users/:id/profile` に更新し、
最新のユーザープロフィールデータを取得します。

クローズ #456

優れたコミットメッセージを書くためのヒント

• 頻繁に、しかし論理的にコミットする： 単一の論理的な変更を表す、小さくアトミックなコミットを作成します。これにより、メッセージが書きやすく、理解しやすくなります。
• プロジェクトの将来の自分の視点からメッセージを書く： 6ヶ月後にこのコミットを振り返っている自分を想像してください。変更を素早く理解するためにどのような情報が必要ですか？
• 具体的に書く： 「コードを更新」や「バグ修正」のような曖昧なメッセージは避けてください。何が更新または修正されたのかを正確に説明します。
• コード参照にはバッククォートを使用する： ファイル名、関数、変数名に言及する場合は、バッククォート（`）で囲みます。
• メッセージをレビューする： コミットする前に、少し時間を取ってメッセージを読み直してください。意味が通っていますか？明確ですか？

まとめ

レビュー、ロールバック、またはインシデントの際に読む人のために、各コミットメッセージを書きましょう。短い命令形の件名を使用し、理由が明らかでない場合は本文を追加し、各コミットを1つの論理的な変更に集中させてください。