2020/02/12

review されやすい PR の description を作成するために、自分が普段どこに意識を向けているのかを整理してみた。大きく「背景」と「変更の概要」を明瞭にすることが重要だと自分は考えている。

• 背景
  • 解決したい課題を明らかにすることで、変更を行うことの妥当性を理解してもらう
  • 既に Issue やチケット上で問題が提起されているのであればリンクを添付しつつ、サマリも簡単に記載する
    • 添付されているだけのリンクは参照されない、見るべきかどうかの判断材料を提示する
• 変更の概要
  • 背景が明確で、変更点が数行のレベルであればそこまで気にしていない
  • 問題は diff が多いケース、どこに着目すべきかが全く分からないと自分は review をする手が止まってしまっている、これは他の人でも一緒のはず
    • review に対する entry point を用意する
      • 言い換えるのであれば「reviewer に対する期待の提示」
      • diff が多すぎて現実問題としてすべてを追うのが難しいのであれば、最低限見てほしい部分にだけコメントを書く
  • 変更点が背景知識への理解に依存しているのであればそれも提示する
    • reviewer がそれを理解しているとは限らない
    • 例えば shell script で利用する command の flag の変更を行ったのであれば、その flag によってどのように挙動が変わるのかを記載する
      • man や help の結果を提示するくらいで十分