はじめに
この記事は
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) ●問題の内容や、どうしてこのプルリクエストが発生したのか把握しておきましょう。 ●全く同意できない場合は、反応する前に数分自分の意見を検討しましょう。 ●命令するのではなく、質問しましょう。︵﹁…しないでください﹂よりも﹁…についてどう思いますか？﹂︶ ●なぜコードの変更を要求しているのか、理由を説明しましょう。︵スタイルガイドに従っていない？ 個人的な好み？︶ ●コードをシンプルに、または改善する方法を提供しましょう。 ●誰かの作成した仕事を参照する際に、﹁バカな﹂などのような軽蔑的な言葉は避けましょう。 ●謙虚にやりましょう。︵﹁あまり分からないけど、試してみましょう…﹂︶ ●誇張を避けましょう。︵﹁絶対に…しない﹂︶ ●グループでの評論を通して、専門的なスキル、グループの知識、製品品質を発展させていくことを目指しましょう。 ●オンラインのコミュニケーションでは、ネガティブなバイアスがかかることに注意しましょう。︵内容が中立であれば、我々はネガティブな発言だと仮定しがちです︶。中立的ではなく、肯定的な書き方が出来ないか考えてみてください。 ●雰囲気を明確にするために絵文字を使いましょう！ ﹁いいじゃん﹂と﹁いいじゃん ﹂を比べてみてください。