Reviewing Patches in the Git Project

パッチの diff のコード変更に加えて、コミット・メッセージの内容が正確で明確であることを忘れずに確認してください。 パッチのコミット・メッセージは、 diff によるコード変更を正確かつ完全に説明する必要があります。

テスト・カバレッジのレビューは、重要ですが見落としがちなレビューのコンポーネントです。 パッチの変更は既存のテストでカバーされる場合もあれば、新しい動作を実行するために新しいテストが導入される場合もあります。 パッチまたはシリーズをローカルでチェックアウトすると、新規および既存のテストの行を手動で変更して、予想される 成功/失敗 の動作を検証できます。 この情報を使用して、適切なカバレッジを検証したり、作者が追加できる追加のテストを提案したりできます。

推奨事項を提供するときは、それを「ブロッキング」(blocking)(問題が修正されない場合、コードが破損するか、または悪化する) と見なすか、「非ブロッキング」(non-blocking)(パッチは推奨事項に従うことで改善される可能性がありますが、シリーズの受け入れにはそれが必須ではありません)と見なすかをできるだけ明確にしてください。 非ブロッキングの推奨事項は、それらがシリーズに関連しているがシリーズの範囲外である場合(「あると便利」なパターン)、または著者とレビュアーの間の文体の違いのみを表す場合、特にあいまいになる可能性があります。

問題についてコメントするときは、作者がそれを修正する方法について提案を含めるようにしてください。 これは、作者が問題を理解して修正するのに役立つだけでなく、あなたのトピックに対する理解を深め、改善することにもなります。

レビューは問題点のみを指摘しなければならない訳ではありません。 肯定的なレビューは、 パッチが対処する問題に関心を持っているのはパッチの元の作成者だけではないことを示しており、 そして、 そうすることは強く推奨されています。

職場の同僚のシリーズについて肯定的なレビューを与えることを躊躇しないでください。 肯定的なレビューがうまく書かれていれば、 他のコミュニティ・メンバーにとっては興味のないシリーズを企業の利益を代表して押しつけているようには見えません。

目標やアプローチやパッチの実装を支持する理由を他の人が理解できるような方法で肯定的なレビューを書いてください。 シリーズを徹底的に読み、 パッチが適切に作成されていると言えるほど問題領域を十分に理解していることを必ず証明してください。 レビューでは自由に「声に出して考えて」(think out loud)ください。 パッチの複雑なセクションをどのように読んで理解したかを説明したり、 混乱した点について質問したり、 非常によく書かれていると感じた点を指摘したりしてください。

特に、 気分を高揚させるフィードバックは、 貢献者が Git コミュニティにもっと積極的に参加するよう奨励するのに大いに役立ちます。

関連するパッチへの平文の Reply-All 電子メールで、パッチごとにレビュー・コメントを提供します。 コメントは、関連するセクションのすぐ下にインラインで作成する必要があります。

パッチdiffで提供される限定されたコンテキストでは、完全なレビューを行うには不十分な場合があります。 このような場合、git-am(1) でパッチを適用するか、シリーズが追跡されたら https://github.com/gitster/git から関連するブランチをチェックアウトすることで、ローカル・ツリーでパッチを確認できます。

既存のコードをリファクタリングする場合など、 大規模で複雑なパッチdiffが避けられない場合があります。 このようなパッチを解析(parse)するのが難しい場合は、 --color-moved および/または --ignore-space-change オプションで生成されたdiffを確認してみてください。

パッチが長い場合は、レビューに関係のない部分を電子メールの返信から削除することをお勧めします。 但し、読者があなたのコメントを理解できるように、十分な文脈を残してください！

シリーズの完全なレビューを一度に完了することができない場合は、シリーズの残りをレビューする予定があるかどうか、またはその時期を作者に知らせることを検討してください。