PR のレビューコメントの解決

目的

pull request のレビューコメントを正確に分析する方法を定める。 各コメントが対応を要するかを判断し、要るときは必要な変更を具体的に書く。

分析の手順

1. 入力を集める

• 対象の PR の未解決のレビューコメントをすべて取得する
• コメントごとに、参照先のファイルと周りのコードを読む。コメントの文面だけで判断せず、コードから判断する

2. 関連するコードを調べる

• diff の hunk だけでなくコードベース全体から、指摘されたコードと同じか似たパターンの箇所 (重複した ロジック、共有のヘルパー、コピーして貼ったブロックなど) を探す
• コメントが対象とするコードの呼び出し元、呼び出し先、依存元を特定する
• 提案された変更を当てると、関連する箇所に連鎖した変更が要るかを判断する

3. コメントを評価する

• レビュアーが何を求めているかを理解する。レビュアーの意図を保ち、コメントを解釈し直したり、範囲を 広げたり、レビュアーが挙げていない改善を足したりしない
• 実際のコードと、手順 2 の関連するコードの調査に基づいて、求めが妥当かを判断する
• コメントを分類する。fix、answer の順に確かめ、残りを skip とする
  • fix: コメントが実際の問題を指し、具体的な変更がある。「これは X では?」のような問いの形のコメントでも、 調査から具体的な変更が出るなら fix とする
  • answer: fix ではなく、変更が要らない確かな理由が調査から得られる。返信で解決する。質問、確認の依頼、 対応済みのコメント、調査で否定される主張がこれにあたる
  • skip: fix でも answer でもない。コメントが曖昧か主観的で調査では決着がつかないか、レビュアーの意図を 特定できない
• 迷ったら skip に分類する (fail-closed)
• answer と skip では、「理由」の節をレビュアーへの返信として書く。何を確かめ、なぜ変更が要らないかを 書く。返信の投稿は別の手順で、ユーザーの指示が要る
• コメントが文書化された規約や原則 (doc-conventions の規則や ADR など) を挙げるときは、その規約に照らして 判断する。同じパターンがコードや文書の他の箇所にあることは、そのままにする理由にならない
• 同じ問題にレビュアーの提案より良い解決策があるときは、代替案として出力に含める

出力の形式

template.md のテンプレートを使う。