コミットメッセージ
ぼくの書き方
コミットメッセージは日記!!!
基本方針として、あとからそのコードの変更根拠を辿らなければいけなくなった場合に、必要な情報にありつけるよう、できるだけ多く情報を残す
最初の行は見出しとなるため、変更を簡潔にまとめる
変更の型を示す
ぼくがよく使う: feature ・ fix ・ improve ・ docs ・ examples ・ refactor ・ performance ・ aesthetics ・ ui ・ design ・ chore ・ test ・ deps ……
1行でわかる変更の要約を示す
要約に挙げた変更を行うため、具体的にどのような変更を行ったかを示す
変更に際して、コーディング規約や作業フロー等の規則に従う必要があった場合、それを示す 変更の結果、ユーザや開発者が行動・順応する必要がある場合、それを示す
必要に応じて、変更を行った際の感情を示す
嬉しいのであれば、嬉しさをしっかりアピールする
ダーティー・難解なコードとなっている場合、それを示す
関連するコミットがあれば、それをコミットハッシュで示す
どのコミットに対する修正?
どのコミットの続きの変更?
参考リンクがあれば、それを張る
参考にした主なリファレンス・記事・例など
例
code:message
fix: ローディングバーの挙動を修正
WebGL側のシェーダのコンパイルに処理が持っていかれていてローディングバーが全然動いてくれなかったので、シェーダのコンパイル処理にTimeSlicerを導入
TimeSlicerの実装は以下を参考にした:
だいぶ読み込み進捗はわかりやすくなったよ
ちょっと読み込み時間自体は前より遅くなっちゃってるかも…… TimeSlicerの改善を次コミットで試みる
シェーダコンパイル部分の既存コードに対してTimeSlicerをぶち込むのがややしんどくて、かなりダーティーなコードにはなりました
リリース後に改善を試みたほうが良さそう
新規関数を実装するにあたり、以下のコーディング規約にある命名規則を参照した:
上の例は、考えうるあらゆるコミットメッセージのパターンをすべて盛り込んでいるため、さすがに長すぎる気はするが、変更内容の大きさを鑑みるとこのくらいの分量あっても別に全然いいんじゃないかと思います
デメリット
もちろん、コミットメッセージを書く分量が増えるのに従って脳のリソースを使うため、書くのに時間がかかる
ちゃんと書いておかないとのちのち困ることを考えたら安い安い
逆に、書き捨てのコードや短期プロジェクトにおいては、それこそメンテナビリティよりも時間パフォーマンスが要求されるため、コミットメッセージを丁寧に書く優先度は下がる
でも君が今書いているそのコードは本当に書き捨てで済むかな~~??あとで考古学とかしない?
丁寧に書くといつ嬉しいか?
コミットメッセージがいつ見られるかに着目する
「このコミットの変更の基本方針は?」
「このコードは今回のPull Requestの主旨にどう関わっている?」
「このロジック・関数の元ネタは?」
「なぜこのコードまで変更する必要があった?」
「これはついでにやった変更?」
ファイルの変更頻度・あるいは変更理由の傾向を知りたいとき
「このコードいじりたいけど、こういう理由でいじって良いコードなんだっけ」
「このコードってどのくらいの頻度で触られるんだっけ」
ファイル・あるいはコード内の特定行の意図を知りたいとき
「このコード、なんでいじる必要があったんだっけ」
「このコード、なんでこんなロジックになってるんだっけ」
啓蒙のプロセス
レビューさせる
考古学をさせる
コミットメッセージの見方
Log
コミットメッセージは、もちろん git log コマンドで確認できる
https://gyazo.com/90438a53c6f591d56bf0e8eba41efc15
GitHub上では、ブランチのHistoryやPull RequestのCommitsからコミットを確認できる
Descriptionsはデフォルトでは閉じられているが、開いて確認することができる
https://gyazo.com/909e4255853719c0494a60b24a13e399
Blame
マウスオーバーすると長文のDescriptionsを書いていてもそれが全部表示される
https://gyazo.com/349d01781b5bd6962848e214baa067b8
あるいは同様に、GitHub上のBlame Viewでも以下のようにコミットメッセージが表示される https://gyazo.com/dd277dbbabbcc5ab19650374afb3f9bf
以上のような機能を駆使して、自分が今から行おうとしている変更・修正に対して、それを行って良いという根拠を得て確信度を上げる アンチパターン
wip
56すよ?
trivial fix
それ本当にtrivial?
修正の意図は?
どのコミットに関連する?
"fix" よりも、 "typo", "leftover", "design" みたいなもっと解像度の高い語彙がない?
CharacterControllerの変更
機能追加?修正?
何を変更した?
変更の意図は?
EventEmitterの修正
何を修正した?
なんでそれで直ると思った?
なぜ修正が必要だった?どのタスク?
英訳のアップデート
なぜアップデートした?
そのタスクが生まれた起点は何?Slackのリンクは?
READMEの更新
何を更新した?
更新の意図は?関連するコミットがある?
レビュー対応
何をしたの?
どのレビューに対する対応?リンクは?