🌟
良いコミットメッセージのルールメモ
1. はじめに
開発において、メッセージを書く機会は多い。
コード/テストコード/コミットログ/コードコメントなど。
これらは、書く時間より読まれる時間のほうが長いので、書く時のコストより読む人にとってのコストを意識して、書くべき。
各々については、下記を意識すると良い。
| 対象 | 記述内容で意識すること |
|---|---|
| コード | How （どのように動かすか） |
| テストコード | What （テスト対象コードの仕様は何をするものか） |
| コミットメッセージ | Why（コードやテストコードから読み取れない、「それはなぜその変更をしているのか」という情報） |
| コードコメント |
Why not（なぜやってないかの理由） コードの説明をしてしまうと、二重管理になってしまう為、避ける。 例：ここは XXX を使うべきだが、hogehogeの理由で仕方なく YYY を使っている） |
2. なぜ良くしたいか
- チーム作業において、円滑な共同編集ができるようにしたい。
- 「良い変更履歴」を定義しルール化することで、認識ずれや理解やレビューにかかる時間のロスを減らす。
- コミットのメッセージから、コミットの内容がある程度予想できるようにすることで、他のメンバーが理解にかかる時間を短縮したい。
3. いいコミットメッセージの定義
3.1. なぜそのコードの変更をしたのかがわかる
望ましいのは、コードをどのように変更したのかではなくなぜコードを変更したのかが書かれていること。
コードをどのように変更したのか、はコードの変更履歴を見ればわかるが、「なぜコードを変更したのか」はコードの変更履歴だけではわからない為。また、なぜコードを変更したのかが説明できるコミットの粒度にするべき。
- 1つの目的に対して、1つのコミットとする
- 意味のない（なぜを説明できない）コミットはまとめる
- コミットは、プリリクエストによるレビュー時に、見られる前提で作る（レビューしやすいコミットを心がける）
3.2. ぱっと見で理解しやすい
何のコード変更なのかがカテゴライズされている、以下のような「プレフィックス（後述）」を先頭に付ける。
3.3. 関連する情報への誘導
コードの差分だけでは読み解けない、書き手の背景を理解する上で必要な情報を、（存在する場合）書く
たとえば仕様が記載されたドキュメントURLや、関連チケット番号、チャットツールのメッセージURLなどをコミットメッセージに書くなど。
4. 具体的なルール
4.1. コミットサマリの先頭には、プレフィックスをつける
| プレフィックス | 説明 |
|---|---|
| feat: | 新機能 |
| fix: | バグの修正 |
| docs: | ドキュメントのみの変更 |
| style: | コードの動作に影響しない、見た目だけの変更（スペース、フォーマット、欠落の修正、セミコロンなど） |
| refactor: | バグの修正や機能の追加ではないコードの変更 |
| perf: | パフォーマンスを向上させるコードの変更 |
| test: | 不足しているテストの追加や既存のテストの修正 |
| chore: | ビルドプロセスやドキュメント生成などの補助ツールやライブラリの変更 |
5. コミットメッセージ例
過去形にしない。（可能であれば）影響範囲（スコープ）が想像できる内容にする。
- ❌ 不具合が起きていたので、修正した
- ❌ apidoc更新
- ❌ レビュー指摘対応
- ⭕️ refactor: 重複する関数の記述を1つにまとめた
- ⭕️ refactor: XXXという変数がこれこれこういう誤解を招いたためより意味のある名前に変更
- ⭕️ refactor: ugafugaというメソッドは非推奨になったので推奨されるメソッドに変更
- ⭕️ fix: hogehogeというサードパーティモジュールにはこういう脆弱性があるので脆弱性がないものに変更
- ⭕️ doc: typo
- ⭕️ perf: ユーザ一覧画面にて、必要なデータをDBから取得するロジックでN+1が発生していたので、実行しているクエリの条件式でin句を使うように修正
あとは、メッセージの先頭に絵文字を入れて、モチベーションを上げるカルチャーも一部ではあるらしい（あまり使わない）
- 例： 🎉 :sparkles: ISSUE #XXで定義した新機能を追加
Discussion