GitHub プルリクエスト完全チートシート

## 目次
1. [プルリクエストの基本](#1-プルリクエストの基本)
2. [効果的なPR作成の手順](#2-効果的なpr作成の手順)
3. [良いPRの特徴](#3-良いprの特徴)
4. [PR説明文の書き方](#4-pr説明文の書き方)
5. [GitHubインターフェースの要素解説](#5-githubインターフェースの要素解説)
6. [レビュアーの追加と通知](#6-レビュアーの追加と通知)
7. [PRレビューの方法](#7-prレビューの方法)
8. [レビューコメントの書き方](#8-レビューコメントの書き方)
9. [PRの承認と拒否基準](#9-prの承認と拒否基準)
10. [レビュー指摘対応と再レビュー依頼](#10-レビュー指摘対応と再レビュー依頼)
11. [Git/GitHub便利コマンド](#11-gitgithub便利コマンド)
12. [PRテンプレート例](#12-prテンプレート例)
13. [トラブルシューティング](#13-トラブルシューティング)

## 1. プルリクエストの基本

### 1.1 プルリクエストとは
プルリクエスト（PR）は、あるブランチで行った変更を別のブランチ（通常はメインブランチ）にマージする前に、その変更をレビューするためのGitHubの機能です。

### 1.2 プルリクエストの目的
- コードレビューを促進する
- コードの品質を確保する
- チームメンバーに変更内容を共有する
- 変更履歴を記録する
- CIパイプラインによるテストを実行する

### 1.3 PRのライフサイクル
1. フィーチャーブランチの作成
2. コード変更とコミット
3. プルリクエストの作成
4. 自動テストの実行
5. レビュー依頼
6. フィードバックと修正
7. 承認
8. マージ

## 2. 効果的なPR作成の手順

### 2.1 ブランチ作成
git checkout main
git pull origin main
git checkout -b feature/new-feature

### 2.2 変更実装とコミット
git add .
git commit -m "機能の簡潔な説明"

### 2.3 リモートにプッシュ
git push -u origin feature/new-feature

### 2.4 GitHubでPR作成
- リポジトリページで「Compare & pull request」ボタンをクリック
- または「Pull requests」タブから「New pull request」をクリック
- ベースブランチと比較ブランチを選択
- タイトルと説明を記入
- レビュアーを割り当て
- 「Create pull request」をクリック

### 2.5 PRの更新方法
git add .
git commit -m "レビュー指摘の修正"
git push origin feature/new-feature

## 3. 良いPRの特徴

### 3.1 サイズと範囲
- **小さく保つ**: 理想は200-400行程度の変更
- **単一の目的**: 一つのPRにつき一つの機能や修正
- **レビューしやすい**: 複雑すぎる変更はさらに小さく分割する

### 3.2 準備と品質
- 自分自身で事前レビューを行う
- ローカルでテストを実行してから提出
- コーディング規約に従っている
- コメントや文書が適切

### 3.3 タイミング
- 早めに作成（WIP状態でも）して方向性の確認を得る
- 大きな機能は小さなPRに分割して段階的に提出

## 4. PR説明文の書き方

### 4.1 基本構成
1. **何を解決するか**: 問題や要件の簡潔な説明
2. **どのように解決するか**: 実装アプローチの概要
3. **なぜこの方法か**: 選択した実装方法の理由
4. **テスト方法**: 動作確認手順
5. **スクリーンショット**: UI変更がある場合

### 4.2 効果的な説明の例
```
## 概要
ユーザー登録フォームでパスワード強度の検証を追加

## 変更内容
- パスワード強度を検証するバリデーション機能を実装
- 強度に応じたビジュアルインジケーターを追加
- エラーメッセージの多言語対応

## 動作確認方法
1. `/register` にアクセス
2. パスワード入力時に強度が表示されることを確認
3. 弱いパスワードでエラーが表示されることを確認

## スクリーンショット
[画像]

## 関連チケット
JIRA-1234
```

### 4.3 参照の活用
- 関連するIssueへのリンク: `#123`
- 特定のコミットへのリンク: `SHA`
- チームメンバーへの言及: `@username`

## 5. GitHubインターフェースの要素解説

### 5.1 PR画面の右サイドバー要素

#### 5.1.1 Reviewers（レビュアー）セクション
- **用途**: PRのレビューを依頼する担当者を指定
- **操作**: 「Reviewers」の右にある歯車アイコンをクリックして追加
- **通知**: 指定されたユーザーにメール・GitHub通知が送られる

#### 5.1.2 Assignees（担当者）セクション
- **用途**: このPRの担当者（主に作成者自身）を指定
- **操作**: 「Assignees」の右にある歯車アイコンをクリックして追加
- **意味**: このPRに責任を持つ人を明示する

#### 5.1.3 Labels（ラベル）セクション
- **用途**: PRの種類や状態を視覚的に分類
- **例**: `bug`, `enhancement`, `documentation`, `wip`など
- **活用**: チーム内でラベルの意味を統一し、PRの管理を効率化

#### 5.1.4 Projects（プロジェクト）セクション
- **用途**: GitHubプロジェクトボードと連携
- **メリット**: タスク管理とPRを紐づけて進捗管理できる

#### 5.1.5 Milestone（マイルストーン）セクション
- **用途**: リリース計画と連携
- **活用**: 特定バージョンに含める変更の管理

#### 5.1.6 Development（開発）セクション
- **Linked issues**: 関連するIssueを表示・リンク
- **Branch**: ブランチ情報と保護状態
- **Deployments**: デプロイ先環境（存在する場合）

#### 5.1.7 その他のアクション
- **Draft/Ready for review**: ドラフト状態と準備完了状態の切り替え
- **Convert to issue**: PRをIssueに変換
- **Lock conversation**: 議論をロック（炎上対策など）

### 5.2 PR操作ボタン
- **Close pull request**: PRを閉じる（マージせずに終了）
- **Merge pull request**: 承認されたPRをマージ
- **マージ方法ドロップダウン**:
  - Create a merge commit: マージコミットを作成
  - Squash and merge: 全変更を一つのコミットにまとめる
  - Rebase and merge: コミット履歴を線形に保つ

## 6. レビュアーの追加と通知

### 6.1 レビュアー追加の詳細手順
1. PR画面の右側「Reviewers」セクションを見つける
2. セクション右の歯車アイコン（または「Add」リンク）をクリック
3. ユーザー名（例: `AさんのGitHubユーザー名`）を入力
4. 表示される候補から選択
5. 複数人追加する場合は上記を繰り返す

### 6.2 チームレビュアーの追加
1. レビュアー追加画面でチーム名（例: `frontend-team`）を入力
2. 表示される候補からチームを選択
3. これによりチーム全員に通知が行き、誰か一人が対応可能

### 6.3 レビュー依頼のベストプラクティス
- 適切な担当者を選ぶ（コードオーナーや関連機能の専門家）
- コンテキストを持つ人を優先（当該機能の背景を知っている人）
- PRの説明欄で特定部分へのレビュー依頼を明記
  ```
  @username このAPIエンドポイントの実装について特にレビューお願いします。
  ```
- 口頭やチャットでも軽く声をかけると良い

### 6.4 レビュー依頼の通知
- GitHubからのメール通知
- GitHub上の通知ベル
- Slack連携している場合はSlack通知
- GitHub for Mobile アプリでの通知（スマホ利用時）

## 7. PRレビューの方法

### 7.1 ブラウザ上でのレビュー操作

#### 7.1.1 ファイル表示の切り替え
- **Files changed**: 全ての変更を一覧表示（デフォルト）
- **File filter**: 特定のファイルタイプやパスだけを表示
- **表示モード切り替え**:
  - Unified: 変更前後を一つの表示で（デフォルト）
  - Split: 変更前後を左右に分けて表示
- **表示設定**:
  - Hide whitespace changes: 空白の変更を非表示
  - Display the rich diff: リッチ表示（画像差分など）

#### 7.1.2 効率的なレビュー方法
1. **「Files changed」タブでの全体確認**
   - 右上の「Viewed」ボタンでレビュー済みファイルにチェック
   - ファイル数が多い場合はフィルターで分類

2. **コメント付け方**
   - 特定の行にカーソルを合わせると「+」アイコンが表示
   - クリックしてコメント入力
   - 「Add single comment」: 即時投稿
   - 「Start a review」: レビューを開始しコメントを蓄積

3. **複数行コメント**
   - 行番号をクリック＆ドラッグで範囲選択
   - 表示される「+」アイコンからコメント

4. **提案機能の活用**
   - コメント入力時に「Suggest change」ボタンをクリック
   - 変更案を直接コードとして提案可能
   - 受け入れる側は「Commit suggestion」で即時適用可能

5. **レビュー完了**
   - 右上の「Finish review」ボタンをクリック
   - 3つの選択肢:
     - **Comment**: 一般的なフィードバック（承認・拒否なし）
     - **Approve**: 承認してマージ可能に
     - **Request changes**: 修正必須の問題あり

### 7.2 効果的なレビュー手順
1. PR説明文を読み、目的と変更概要を理解
2. 自動テスト結果を確認（CI/CDの結果）
3. 全体の変更量と影響範囲を把握
4. コア機能の変更から確認（重要なファイルから）
5. 関連ファイルをグループで確認
6. 変更の整合性をチェック（複数ファイル間の整合性）
7. UIの変更がある場合はスクリーンショットを確認
8. 最終的な結論（Approve/Request changes）を付ける

### 7.3 効率的なレビューのコツ
- **「Viewed」機能の活用**: レビュー済みファイルを管理
- **キーボードショートカット**:
  - `?` で全ショートカット表示
  - `n`, `p` で次/前のコメントに移動
  - `a` でApprove、`r` でRequest changes
- **コミット履歴の確認**:
  - 「Commits」タブで変更の流れを把握
- **レビュー前の「Conversation」タブ確認**:
  - 他のレビュアーのコメントを事前チェック
- **View file** ボタンで全体コードを確認:
  - 差分だけでなく全体のコンテキストを理解

## 8. レビューコメントの書き方

### 8.1 良いコメントの特徴
- 明確で具体的
- 根拠を説明する
- 解決策を提案する
- 礼儀正しく敬意を持つ
- 質問形式を活用する

### 8.2 コメント例
**悪い例**:
「この実装は良くない」

**良い例**:
「この処理はループごとに新しい配列を作成するためO(n²)の時間複雑度になります。代わりにマップを使用して一度の走査で処理することで、O(n)に改善できると思います。例: 
const result = array.reduce((acc, item) => {...}, {});」

### 8.3 フィードバックのレベル分け
- **Must Fix**: セキュリティ、バグ、重大なパフォーマンス問題
- **Should Consider**: ベストプラクティス、リファクタリング提案
- **Discussion**: 代替アプローチの提案、質問

## 9. PRの承認と拒否基準

### 9.1 承認基準
- 機能要件をすべて満たしている
- 自動テストがすべて通過している
- コーディング規約に準拠している
- セキュリティリスクがない
- パフォーマンス要件を満たしている
- 必要なドキュメントが更新されている

### 9.2 条件付き承認
- 軽微な修正が必要だが、後続のPRで対応可能
- 「Approve with suggestions」として承認

### 9.3 拒否基準（Changes Requested）
- 要件を満たしていない
- セキュリティ上の問題がある
- 重大なパフォーマンス問題がある
- テストが不十分または失敗している
- アーキテクチャ上の問題がある

## 10. レビュー指摘対応と再レビュー依頼

### 10.1 レビュー指摘の確認と整理

#### 10.1.1 レビューコメントの確認方法
1. **Conversation**タブでレビューを確認
   - すべてのレビューコメントがスレッド形式で表示される
   - 各レビュアーの意見を一覧で把握できる

2. **Files changed**タブでのコメント確認
   - コード行ごとのコメントをコンテキスト付きで確認
   - 複数のレビュアーからのコメントもファイル・行単位で集約される

3. **メール通知の活用**
   - レビューコメントが付くとメール通知が来る
   - メールのリンクから直接該当箇所に移動できる

#### 10.1.2 レビュー指摘の整理手順
1. **指摘事項を分類する**
   - 必須修正（Must Fix）: すぐに対応が必要
   - 検討事項（Should Consider）: 検討の上、対応を判断
   - 議論事項（Discussion）: 方針の確認が必要

2. **修正計画を立てる**
   - 優先度付け: セキュリティ > バグ > 機能 > リファクタリング
   - 依存関係の整理: 影響範囲が広いものから着手
   - 難易度評価: 簡単な修正から進めると効率的

### 10.2 レビュー指摘への回答方法

#### 10.2.1 GitHub上での回答方法
1. **コメントに直接返信**
   - コメント下の「Reply...」欄に回答を入力
   - 「Add a single comment」をクリック
   - または「Start a review」で複数コメントをまとめて返信

2. **Resolve conversation**の使い方
   - 修正完了後、「Resolve conversation」をクリック
   - 修正方針を記載してから解決するのがベストプラクティス
   - 例: 「指摘の通り修正しました。O(n)の実装に変更しています。」

3. **提案の受け入れ方**
   - 「Suggested change」に対しては「Commit suggestion」可能
   - 複数の提案をまとめて「Commit suggestions」も可能
   - カスタマイズする場合は「Apply suggestion」でエディタに取り込み

#### 10.2.2 効果的な回答の書き方
1. **修正内容の明示**
   - 何をどう修正したかを具体的に説明
   - 変更箇所へのリンクや行番号を含める

2. **方針の説明**
   - なぜその修正方法を選んだのかの根拠
   - 代替案を検討した場合はその比較結果

3. **質問への回答**
   - 明確かつ簡潔に
   - 必要に応じて補足資料やドキュメントへのリンク

4. **議論が必要な場合**
   - 「Let's discuss」などと明示して議論を促す
   - Slackやミーティングなど別の場での議論を提案する場合もあり

#### 10.2.3 回答例
**良い回答例**:
「ご指摘ありがとうございます。O(n²)の問題を修正し、Mapを使ったO(n)の実装に変更しました。具体的には、二重ループではなく`reduce`を使用して一度の走査で結果を構築しています。[変更箇所へのリンク]をご確認ください。これにより、大量データ処理時のパフォーマンスが約3倍向上しました。」

### 10.3 指摘事項の修正と新コミットの作成

#### 10.3.1 修正手順
1. **ローカル環境での修正**
   - 最新のリモート変更を取得
   ```
   git checkout feature/branch
   git pull origin feature/branch
   ```
   
   - 指摘内容に基づいてコードを修正
   - 修正内容をテスト（ローカルテスト実行）

2. **修正のコミット**
   - 分かりやすいコミットメッセージを作成
   ```
   git add .
   git commit -m "レビュー指摘対応: パフォーマンス問題の修正（O(n²)→O(n)）"
   ```

   - 複数の指摘がある場合は、内容ごとに分けてコミットするとレビューしやすい
   ```
   git add file1.js
   git commit -m "レビュー指摘対応: バリデーション強化"
   git add file2.js
   git commit -m "レビュー指摘対応: エラーメッセージの多言語対応"
   ```

3. **コミットの整理（オプション）**
   - 小さなコミットが多すぎる場合はrebaseで整理
   ```
   git rebase -i HEAD~3  # 直近3コミットを整理
   ```
   
   - pickをsquashに変更することで関連コミットを統合可能

4. **リモートへのプッシュ**
   ```
   git push origin feature/branch
   ```

#### 10.3.2 コミットメッセージのベストプラクティス
- **接頭辞の活用**: 「Fix:」「Review:」「Refactor:」など
- **何をなぜ変更したかを記載**: 「NullPointerExceptionを回避するため、nullチェックを追加」
- **関連チケットやコメントへの参照**: 「Ref: #コメントID」や「Fix #IssueID」

### 10.4 再レビュー依頼の方法

#### 10.4.1 GitHub上での再レビュー依頼
1. **PR説明文の更新（オプション）**
   - 「Edit」ボタンから説明文を更新
   - 修正概要や確認してほしいポイントを追記

2. **レビュアーへの通知**
   - PR画面上部の「Re-request review」ボタンをクリック
   - または特定のレビュアーの名前横の「Re-request」をクリック
   
3. **Conversation**タブでのコメント
   - 全体向けコメントを追加
   - 例: 「レビュー指摘事項を全て修正しましたので、再度レビューをお願いします。特に○○の部分をご確認ください。」

4. **特定のレビュアーへのメンション**
   - `@username` で特定のレビュアーに通知
   - 例: 「@reviewer_name パフォーマンス問題を修正しました。ご確認いただけますか？」

#### 10.4.2 再レビュー依頼のコミュニケーション
1. **修正内容のサマリー**
   - 修正した箇所を簡潔にリスト化
   - 特に重点的に見てほしい箇所を明示

2. **未対応事項の説明**
   - 対応を見送った指摘があれば、その理由を説明
   - 例: 「○○の変更は範囲が大きいため、別PRで対応予定です」

3. **追加の変更点の共有**
   - レビュー指摘以外に追加で変更した点があれば明示
   - レビュー後に気づいた問題の修正など

4. **チャットツールでの補足（オプション）**
   - SlackやTeamsなどで再レビューの依頼を簡潔に伝える
   - 例: 「PRの指摘事項を修正しました。再レビューをお願いします。」

#### 10.4.3 再レビュー依頼メッセージ例
```
@reviewer_name レビューいただきありがとうございます。指摘事項に対応しました。

## 修正内容
1. パフォーマンス問題: O(n²)→O(n)の実装に変更 (app/service.js)
2. エラーハンドリング: 例外発生時のログ出力を追加 (utils/error.js)
3. テスト: エッジケースのテストケースを追加 (tests/service.test.js)

特に1のパフォーマンス改善について重点的にご確認いただけますと幸いです。
再度のレビューをよろしくお願いいたします。
```

### 10.5 レビュー対応後のフォローアップ

#### 10.5.1 レビュー状態の追跡
1. **レビュー対応状況の可視化**
   - GitHubのレビューコメント数/解決済み数を確認
   - 未解決のレビューコメントを確認し、漏れがないようにする

2. **CIの再実行と結果確認**
   - 修正後のCIパイプラインが成功していることを確認
   - テストカバレッジやコード品質指標を確認

#### 10.5.2 再レビュー後の対応
1. **追加指摘への対応**
   - 再レビューで新たな指摘があれば同様のプロセスで対応
   - 繰り返し指摘が発生する場合は、直接コミュニケーションを検討

2. **承認後の対応**
   - 全てのレビューが承認されたらマージ準備
   - 必要に応じてブランチの最新化（rebase or merge from main）

3. **マージ確認**
   - マージ前の最終チェック
   - マージ後のデプロイ状況や動作確認

#### 10.5.3 レビュー完了後の振り返り
1. **レビューの質向上のための振り返り**
   - 頻出する指摘パターンの認識
   - 事前セルフレビューでの確認ポイントの改善

2. **チーム内での知識共有**
   - 重要な指摘や学びはチーム内で共有
   - コーディング規約やベストプラクティスの更新提案

### 10.6 複雑な議論が発生した場合の対処法

#### 10.6.1 意見の相違への対応
1. **オフラインでの議論**
   - PR上でのコメント交換が3往復以上になる場合は直接会話を検討
   - ビデオ会議や対面での議論を設定

2. **第三者の意見を求める**
   - 技術リードや他のチームメンバーに判断を仰ぐ
   - チーム全体で議論する価値がある場合は会議設定

3. **妥協案の提示**
   - 双方の意見を尊重した中間的な解決策を検討
   - 短期的な対応と長期的な対応を分ける

#### 10.6.2 タイムボックス管理
1. **議論の時間制限設定**
   - 長期化するPRは品質低下やマージ遅延のリスク
   - 一定期間（例: 3営業日）を超える場合は意思決定プロセスを明確化

2. **段階的アプローチの検討**
   - 複雑な機能は段階的にマージすることを検討
   - 「まずは最小限の実装をマージし、改善は次のPRで」などの提案

## 11. Git/GitHub便利コマンド

### 11.1 レビュー前のローカル準備
```
git checkout main
git pull
git checkout feature/branch
git rebase main
```

### 11.2 PRのローカル確認
```
git fetch origin pull/ID/head:PR-NAME
git checkout PR-NAME
```

### 11.3 特定のPRのマージ確認
```
git checkout main
git merge --no-ff --no-commit origin/feature/branch
# 確認後
git merge --abort
```

### 11.4 コミット履歴の整理
```
git rebase -i HEAD~3  # 直近3コミットを整理
```

## 12. PRテンプレート例

GitHubでは`.github/PULL_REQUEST_TEMPLATE.md`ファイルでPRテンプレートを設定できます。

```
## 変更概要
<!-- 変更の概要を簡潔に記述してください -->

## 変更の種類
- [ ] バグ修正
- [ ] 新機能
- [ ] 機能改善
- [ ] リファクタリング
- [ ] ドキュメント更新
- [ ] その他

## 関連Issue
<!-- 関連するIssue番号を記載してください e.g. #123 -->

## 動作確認手順
<!-- 動作確認の手順を記載してください -->

## スクリーンショット
<!-- UI変更がある場合はスクリーンショットを添付してください -->

## 特記事項
<!-- レビュアーへの特記事項があれば記載してください -->
```

## 13. トラブルシューティング

### 13.1 コンフリクトの解決
```
git checkout feature/branch
git fetch origin
git merge origin/main
# コンフリクト解決
git add .
git commit -m "Merge main and resolve conflicts"
git push origin feature/branch
```

### 13.2 マージ後のブランチ削除
```
# リモートブランチの削除
git push origin --delete feature/branch

# ローカルブランチの削除
git branch -d feature/branch
```

### 13.3 CI/テスト失敗時の対応
1. テストログを確認
2. ローカルで同じテストを実行
3. 修正をコミットしてプッシュ
4. CI再実行

### 13.4 レビュー指摘の反映漏れ防止
- GitHub PR画面で「Resolved conversations」を確認
- 「Files changed」タブで「View changes」から差分を確認
- レビュー前に自己チェックリストを作成して確認

## 参考リンク

- [GitHub公式ドキュメント: プルリクエストについて](https://docs.github.com/ja/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests)
- [GitHub公式ドキュメント: プルリクエストのレビュー](https://docs.github.com/ja/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews)
- [GitHub公式ドキュメント: PR指摘への対応](https://docs.github.com/ja/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request)
- [GitHub公式ドキュメント: PRテンプレート](https://docs.github.com/ja/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository)
- [Conventional Commits](https://www.conventionalcommits.org/ja/v1.0.0/)

このチートシートを活用して、効率的かつ効果的なGitHubでのプルリクエスト作成とレビューを行ってください。