よいコミットメッセージとはどういうものだろう? - chiastolite’s blog に対するアンサーソングです
必要であればWhyを補足するためのContextを書く
元エントリだとコミットメッセージの話だったけど僕はPRで実践してもいいと思います。*1
起点となるURLを明記する
- レビューで指摘されたのであればPRのコメントのURL
- issueのURL
- アプリケーションエラーであればSentryなどのエラートラッキングシステムのURL
- GitHub外のタスク管理ツール(例:redmineやBacklogやTrelloなど)に修正概要が書かれているのであればそのURL
- チャットのやり取りが起因ならSlackなどのパーマリンク
- 公式ドキュメントのURL
- CIがコケているのであればCIのビルドのURL
チーム開発していればコミットやPRを行う起点となるURLがだいたいの場合存在するので、僕はそれを書くようにしています。
理由
- コミットメッセージやPRにWhyを全て書くのは難しいのでそれに付随するContextは別URLを参照させた方が楽
- 特にチャットのやり取りの場合、その当時のリアルなやり取りをコミットメッセージやPRの概要で読み取るのは難しいのでSlackのURLが貼られていると後々他の人が見た時の情報が増える
別に他人に強制するようなものでもないし *2即効性がない(1~2年後の誰かが嬉しくなる可能性があるだけ)のですが、自分がこうされていると嬉しいので日頃からやっています
アプリケーションエラーやCIのビルドエラーであればバックトレースも(全部じゃないけど)書く
これは場合によりけりかな。
SaaSは過去ログが全部残ってることが多いので1年後とかにそのURLを見返すことができます。
しかしSentryやGitLabなどを自前でホスティングしてるような場合に容量的な問題で過去ログを定期的に消していることがあるので、そういった場合にURLだけだとリンク先が消えて詳細な情報が追えなくなるので僕は念の為書くようにしています。