How to write the perfect pull request

Approach to writing a Pull Requestの要約

  • Pull Requestの目的を含める
  • 作業が行われている理由の概要（経緯に精通していることを求めない）
  • 誰もがこのPull Requestを読んでいる可能性があることを忘れない
  • 必要なフィードバックがある場合はそれについて明確に説明
  • Pull Requestが進行中の場合はフィードバックが必要な時期を明記し[WIP]などのタイトル接頭辞を付ける
  • ディスカッションに参加させたい@メンションとその理由を記載
    • 例）/cc @GitHub/security、このアプローチに関する懸念は？

Offering feedbackの要約

  • 問題の文脈とこのPull Requestが存在する理由をよく理解する
  • 同意できない場合、応答する前に数分検討してから
  • Ask, dont’ tell. (“できない”より”なんでそれをするの？”)
  • コードを変更する理由を説明
  • コードを簡略化または改善する方法を提供
  • 中傷的な用語を使用しない
  • 謙虚になる
  • 誇張を避ける
  • グループの批評を通じて、専門的なスキル、グループの知識、製品の品質向上を目指す
  • オンラインコミュニケーションのマイナスバイアスに注意
  • 絵文字を使用してトーンを明確にする

Responding to feedbackの要約

  • 説明を求める
  • 問題解決のために行った決定を説明する
  • すべてのコメントに返信する
  • Followup Commit、またはPull Requestへのリンク
  • 議論が混乱している場合、オフラインで議論し、まとめたフォローアップを投稿することも検討

Pull Request Hell

The Right Way / Being the Creatorの要約

  • Keep an open mind: 建設的な批評の必要がある、そしてそれがPRのすべて
  • Stay focused on your goal: 目的に集中し、大きなリファクタリングをしない
  • Document non trivial lines of code: 重要なコードにドキュメントを
  • Write unit tests for all your changes: PRとともにテストコードを
  • Finally read your code: 最後にコードを読んで簡素化・改善を行う

The Right Way / Being the Approverの要約

  • Make time to review the code: コードを確認する時間を確保
  • Write your own notes before using the tool: ツールを使う前にメモで考えを整理する
  • Make sure you know your standards: 自分の基準を知る
  • Learning, I think this is the most important part of being an approver: 学ぶことがもっとも重要

The Wrong Wayの要約

  • Writing comments just to write comments: コメントを書くためだけのコメント
  • Not learning: 学ばない
  • Creating a backdoor: 自分のコードを承認するバックドアを作る
  • Constantly commenting on Syntax and Styling: コーディング規約コメントばかりしている

10 tips for better Pull Requests

10 tips for better Pull Requestsの要約

  1. Make it small: 小さく焦点を絞ったPull Request/1ダース以下のファイル変更なら悪くない
  2. Do only one thing: 1つのPull Requestは1つのテーマのみ扱う、or Welcome to Merge Hell
  3. Watch your line width: レビュアーがdiffしやすいように
  4. Avoid re-formatting: フォーマットを変更したければ別Pull Requestで
  5. Make sure the code builds: 最低でも動くものを
  6. Make sure all tests pass: 最低でも自動テストをパスするものを
  7. Add tests: テストの追加も
  8. Document your reasoning: 理由を書く
    • 「何を」書いたのかではなく、「なぜ」その方法でコードを書いたのかを説明
  9. Write well: 正しく作文する
  10. Avoid thrashing: スラッシング（無意味なコミット履歴）を避ける

Document your reasoningの要約

  1. Self-documenting code: 自己文書化したコード
  2. Code comments: うまく自己文書化できなかったらコメントで
  3. Commit messages: コードに書くことがふさわしくない内容を
  4. Pull Request comments: 自己文書化したコード