完璧なプルリクエストの書き方("How to write the perfect pull request" by Keavy McMinn@GitHub)

GitHub に勤める Keavy McMinn さんのブログの記事「How to write the perfect pull request」の紹介を見たのですが、これは良いなぁと感じたので、翻訳してみました。

間違いもあると思いますので、ご指摘いただけると嬉しいです。

---

完璧なプルリクエストの書き方

会社が大きくなるにつれて、社員とプロジェクトは変わっていきます。我々は、GitHubに必要な文化を保ち続けるためには、コミュニケーションする際に、その目的を自覚することが大切であるということを発見しました。そこで、プルリクエストでの共同作業において、自分達が最高の自分達でいられるように、近年、次のガイドラインを導入しています。

プルリクエストを書く際の手引

• プルリクエストの目的を書きましょう。例えば：

～を調査する技術検証
～の表示の簡素化
～の取り回しの修正

• なぜ現在の仕事をしているのかという概要が書かれてるか確認しましょう（参考リンク付きで）；今までの経緯が周知されていることを仮定してはいけません。
• 全社員がプルリクエストを見れることを覚えておきましょう。内容や雰囲気は、現在、参加していない人にも有益です。
• もしあるなら、欲しいフィードバックを明確に書きましょう：コードにを通してほしい。技術アプローチの議論をしたい。設計についての批評が欲しい。草稿のレビュー。
• もし、出したプルリクエストが途中の段階なら、_いつ_フィードバックが欲しいか伝えましょう。タイトルに「[WIP]」の接頭辞を付けるのは、その事を示すための、単純で一般的なパターンです。(訳注：Work In Progressの略で、意味は仕掛品)
• 議論してほしい人を指定するには、個人に対する**@mention**をして、後ろに論点を書きます。(「/cc @jesseplusplus このロジックを明確にしたいのですが」)
• 議論したいチームへの @mention も、後ろに論点を記述します。(「/cc @github/security, このアプローチに懸念点はある?」)

フィードバックの提供

• 課題の背景や制約と、このプルリクエストが投げられた理由を熟知しましょう。
• 明らかに納得できない際は、答える前に数分間は熟考しましょう; 口に出す前によく考える。
• 一方的に話すのではなく尋ねましょう。（「...をするな」よりも「...してみてはどうですか？」）
• なぜ、コードを変更する必要があるか理由を説明しましょう。（スタイルガイドに沿っていないのではないですか？個人的な好みでしょうか？）
• コードの単純化や改善する方法を提供しましょう。
• 他の人の仕事を引用する際は、「愚か」などの軽蔑的な用語を使用しない。
• 謙虚であれ。（「確信はないのですが、...を試してみてください」）
• 誇張を避けてください。 （「死しても...するな」）
• グループでの評論を通して、専門的なスキル、集合知と製品品質を養うことを目指しましょう。
• オンラインでのコミュニケーションではネガティブなバイアスに注意してください。（内容が中立なときに、私たちはネガティブな雰囲気を仮定します。）中立的ではなく、ポジティブな言葉を使ってみませんか？
• 雰囲気を明確にするために絵文字を使用してください。「 よさそう 」 と 「よさそう」を見比べてみてください。

フィードバックへの対応

• 感謝の気持ちを表しながら進行しましょう。特にフィードバックが白熱したときには重要です。
• 明確にすることを求めましょう。 （「理解できていないので、もう少し説明してもらえませんか？」）
• 明確にするよう求められたら、問題の解決策にたどり着くまでにあなたが行った判断の説明をしましょう。
• すべてのコメントに反応してみてください。
• 元のコミットやプルリクエストへのリンクを付けてください。(「やったぜ! 1682851 が完了」)
• 炎上している時は、コメントのやり取りを続けるのがコミュニケーションの形として現時点で適切か考えてみてください。（仮想的にでも）フェイス·トゥ·フェイスで話してみて、その後にオフラインでの議論を要約するフォローアップを相互に投稿することを検討してください。（投稿は、後で読む人たちに有益です）

これらのガイドラインの一部は、Thoughtbotのコードレビューガイドに触発されています。

私たちのガイドラインは、自分たちの仕事のやり方や育成したい文化に適応させています。皆様のお役に立てれば幸いです。

ハッピーコミュニケーション！

オリジナル

"How to write the perfect pull request", Keavy McMinn, January 22, 2015. https://github.com/blog/1943-how-to-write-the-perfect-pull-request