コミットメッセージの書き方

ここ5年ほど pre commit review があるような環境(主に chromium とか)で働いてきたので、コミットメッセージの書き方を自分なりにまとめておきます。

コミットメッセージで伝えたいことはパッチのコンテキストである

コミットメッセージはコードレビュー依頼であるという態度で記述します(受け売り)。そのため、コードレビュー者がパッチのコンテキストを理解できるように記述するべきです。なにをやっているのか分からないパッチを渡されるより、これはこういう理由でこういう変更をやっているパッチだということを伝えてからパッチを見たほうが、パッチの理解も速いでしょう。レビュー者にパッチのコンテキストを理解してもらえれば、コードレビュー速度が上がったり、コードのミスが見つけてもらいやすくなるという利点があります。

コミットメッセージの基本的なフォーマット

コミットメッセージには一般的に使われる基本的なフォーマットがあり、それにそって記述します。

１行目

１行目はパッチのタイトルのようなものです。なるべく50文字以内で、何をしたのかや改良点を簡潔に書きます。git log --oneline ではここだけ出て来るので、何をやっているのかを簡潔に書きます。ぼくは tig を使って履歴を良く見ていますが、tig でも１行目が git log --oneline と同じように出ます。

例

Implement something to improve stability

Add something

Remove something

50文字を超えない程度なら、to improve stability のように、理由を入れることもあります。

個人的には Fix xxx とか Modify xxx とかはほとんど書きません。自明なので。もっと内容のあることを書きたいからです。

最初は大文字、ピリオドはなし、ということになっているようですので、(最近は)それを守っています。

あとぼくは基本的に英語で書きますが、日本人だけしかいないなら日本語でもいいと思います。OSS にしたいのなら、日本人としては残念ですが英語が標準語になってしまっているので、英語で書いてください。まともな高卒ぐらいの英語力があれば伝わるものは書けると思います。

２行目

２行目は空行です。

ツール類に１行目をタイトルだと認識してもらうため、必ず空行です。

３行目以降

ここからが本番です。まず、このパッチが解こうとしている問題が何なのかを述べるようにします。つまり、このパッチがなかったら、どういうまずいことが起こるのかをレビュー者に伝えます。

このパッチに対応するチケットに問題が詳細に書いてあっても、「このパッチで」解こうとしている問題を述べるようにします。レビュー者がチケットを丁寧に読んでくれると思ってはいけません。チケットに書かれている問題は少し複雑で、いくつかのパッチを積み重ねて解決できるものもあるでしょう。レビュー者には、その問題のどこを解こうとしているのかは（コードを読まなければ）わかりません。コミットメッセージはコードを読む前に読んでもらうもの、という前提なので、コードを読まないと理解できないようなことは原則的には書きません。

例

If parameter `id` is not provided, this function could raise an
Exception, and it's not handled at all.

This update() could take O(N^2) time in the worst case. N is around 10
in the usual case. However, N could be 100 at the worst case, and this
often happens. It is too slow.

基本的に 72 文字以内で改行することが良いことになっています。

問題がレビュー者に伝わったら、それを「どのように (how)」解こうとしているのかを述べます。

例

So, the existence of `id` must be checked in the controller.

So, I implement O(N log N) algorithm like merge sort.

付加情報

最後に、チケットへのリンクやバグ番号を入れておきます。chromium では BUG=123 の形式で書くようになっていますが、github なら #123 のように書きます。

BUG=123

書かなくて良いもの

３行目以降には、べつに「何を (what)」やっているかは詳細には書かなくていいです。それは１行目に完結にまとめてください。１行目に書く必要が無いような情報なら、書かなくていいです。コードを読む助けにはなりません。パッチを見ればわかります。「何をやっているか」はパッチを読めばわかりますが、「なぜやっているか」はパッチを見てもわかりません。ですので、「なぜ」を書いてください。

例

Add class A. Rename A to B.

例外

何事にも例外はつきものです。typo の fix とかは１行メッセージで済ませることもあります。

2017-01-15