はじめに

開発チームでGitとGitHubを利用してソフトウェア開発をしています。スムーズに開発をすすめることを目標としてコミットメッセージ、Issue、Pull Requestのフォーマットを決めたり、Emoji Prefix¹を導入したりしています。
チームや部署で意識を統一するのはとても難しいです。
そんななか、コミットタイトルも、メッセージも、プルリクも全く同じで投稿してあるのをみて😱 なんでー！😱という気持ちになって以下の文章を書きました。
これが正しいというわけでは全くありません。でも、一つの考え方のサンプルにはなるかもしれません。

コミットについて以下の様なコミットフォーマットを採用しています。

1行目: コミットサブジェクト²
2行目: 空行
3行目以降: コミット理由を含む詳細な説明³

コミットサブジェクト

コミットサブジェクトはdiffを見る時の心構えをレビュワーに知らせるために作業内容を簡単に書きます。

例1: :shower: Remove blank lines

空白の行を取り除いたとあります。この場合diffは空行の削除だけのはずです。空行はひと目で空行だとわかるのでレビューも楽です。

例2: :art: Change variable name

変数名を変更したとあります。この場合diffは気をつけてみなければいけません。その変数が出現している箇所すべてが新しい変数名に置き換わっているかどうか確認します。場合によっては変更前の変数名で検索をかけるかもしれません。

このようにコミットサブジェクトが適切だとレビュワーにdiffを見る前にどのようなコミットなのか予想させることができます。レビュワーは心の準備ができるのでメリハリをつけてレビューをすることができます。また、レビュー初心者に対しても注意して見るべきコミットを伝えることができます。

コミットメッセージ

コミットメッセージにはその変更をした理由を詳しく書きます。どれだけ長くなっても良いです。その変更に関するIssueや発言があったらパーマリンクを貼り付けておきましょう。その変更をする理由を詳しく書いておきましょう。このとき、1年後にそのコミット(コミットメッセージとdiff)だけをみて、何がしたくてどのような作業をしたのかわかるようにしておくのがポイントです。こうすることで、変更意図がわからずSlackや口頭で直接本人に質問したり、退職した人が書いたコードでなんのことだかさっぱりわからなくてお手上げといった状況をなくすことができます。人はいつ死ぬかわからないし、コミットメッセージは毎回ちゃんと書いておきましょう。

コミット粒度

ぜひ git add . ではなく git add -p を使いましょう。
インデント修正や空行の削除などプログラムの内容変更と関係ないコミットは、その他のプログラムの変更と一緒にしないでください。プログラムに影響のない箇所がハイライトされます。レビュワーがかわいそう

emoji prefixなどの取り組みは、コミットの粒度を考えるきっかけになるはずです。

Pull Request

複数のコミットで実装したことと実装に至った背景などを書いておきます。Pull Requestは最高です。いいPull Requestをみたら問題解決の方法と過程と答えがすべてわかります。最高。

失敗

コミットメッセージはコミット後でも変更できます。コミットメッセージやコミットの粒度を間違えたらたいていやり直せます。正確な情報をコミットに残しましょう。
コマンドが使えないのは知識がなくて怖いからです。やり方がわからなかったらググッてまずやってみてください。何回も失敗したらできるようになります。エラー文google翻訳したりしてちゃんと読むと答え書いてあります。周りに相談してください。ほんとうに失敗しちゃったら関係者に謝ってなんとか元に戻しましょう。