はじめに
この記事は
How to write the perfect pull request - GitHub
を和訳というか、意訳した記事です。
ご指摘などありましたら大歓迎です！
良いプルリクエストを書くには
(原題 : How to write the perfect pull request)
会社が成長していくと、人もプロジェクトも様変わりしていきます。GitHubの中に私達が望む文化を育んでいくためには、我々が何を自覚してコミュニケーションするべきなのか分かってきました。私達のチームが最強であり続けるために、最近以下のようなプルリクエストのガイドラインを導入しました。
プルリクへのコメント
(原題 : Approach to writing a Pull Request)
-
プルリクエストには目的を明記しましょう。たとえば…
これは〜を調べてみるためのプロトタイプです
これは〜の表示を簡素化します
これは〜の取り扱いを修正します -
プルリクを読む人々が経緯に精通していると思い込まず、なぜその仕事が発生したのか概要を提供するように努めましょう。
-
会社の誰しもがプルリクエストを読めるということを忘れないようにしましょう。今後、今参加している人以外が読んだ時にも、内容や雰囲気がわからなくてはいけません。
-
あなたがどんなフィードバックを望んでいるのか明確にしましょう。例えば「コードに目を通して欲しい」「技術的な議論がしたい」「設計について批評してほしい」「文言を確認してほしい」などです
-
プルリクエストで作業が進行中ならば、いつフィードバックして欲しいかを明確にしてください。タイトルの頭に
[WIP]をつけるのは、作業中であることを示す一般的なやり方です。（訳註：WIPとは Work In Progress 作業中の意味です） -
議論に関与させたい誰かがいるなら
@hogeと指定（mention）しましょう。そしてなぜmentionしたのかを添えましょう。（例: /cc @jesseplusplus ロジックの明確化のため） -
チームに対してmentionする場合も同様に理由を添えましょう。（例 /cc @github/security このやり方で問題ないですか？）
フィードバックの書き方
(原題 : Offering feedback)
- 問題の内容や、どうしてこのプルリクエストが発生したのか把握しておきましょう。
- 全く同意できない場合は、反応する前に数分自分の意見を検討しましょう。
- 命令するのではなく、質問しましょう。（「…しないでください」よりも「…についてどう思いますか？」）
- なぜコードの変更を要求しているのか、理由を説明しましょう。（スタイルガイドに従っていない？ 個人的な好み？）
- コードをシンプルに、または改善する方法を提供しましょう。
- 誰かの作成した仕事を参照する際に、「バカな」などのような軽蔑的な言葉は避けましょう。
- 謙虚にやりましょう。（「あまり分からないけど、試してみましょう…」）
- 誇張を避けましょう。（「絶対に…しない」）
- グループでの評論を通して、専門的なスキル、グループの知識、製品品質を発展させていくことを目指しましょう。
- オンラインのコミュニケーションでは、ネガティブなバイアスがかかることに注意しましょう。（内容が中立であれば、我々はネガティブな発言だと仮定しがちです）。中立的ではなく、肯定的な書き方が出来ないか考えてみてください。
- 雰囲気を明確にするために絵文字を使いましょう！ 「いいじゃん」と「
いいじゃん 
」を比べてみてください。
フィードバックへの対応
(原題 : Responding to feedback)
- とにかくまず感謝を表明してください。特にフィードバックが的確だった場合は！
- 明確化するよう求めましょう。（「ねえよく分からないんだけど、もう少し説明してくれませんか？」）
- 質問されたら、なぜそのような実装に辿り着いたのか説明し、しっかりとわかってもらいましょう。
- できることなら、すべてのコメントに返信してください。
- 関連するコミットやプルリクエストにリンクを貼りましょう（「1682851でしたやつ、名案だね！」）
- 議論の余地があったり混乱が見られる場合は、もっといい言葉をつかって彼らと会話できるのではないか自問してみてください。対面で話し合っているつもりでやりとりし、オフラインで起きている議論を要約した続報をお互いに投稿してみるといいのではないでしょうか。（これから読む人に役にたちます）
このガイドラインは、Thoughtbotのcode review ガイドに触発されて作成しました。
このガイドラインは、我々の仕事の進め方や、我々が育てていきたい文化に適合しています。これを読むあなた達にもそうであることを願っています！
Happy communicating!