Pull Requests & Code Review

This lesson on Pull Requests & Code Review is hands-on and example-driven. You will master GitHub's structured review workflow, enabling you to consolidate all feedback into a single, non-disruptive submission. You will learn to avoid the "notification flood" caused by sequential single comments, ensuring clear communication and efficient code review cycles for your team.

What You'll Be Able To Do

• Initiate a pending review session using the GitHub UI.
• Group multiple line-level comments across different files into one submission.
• Distinguish between an immediate comment and a batched review comment.
• Select the appropriate final decision (Approve, Comment, Request Changes) when submitting feedback.
• Calculate the notification volume difference between batched and unbatched feedback.

Detailed Concept Walkthrough

1. Immediate Comment Fragmentation

Using the 'Add single comment' button immediately notifies the author and watchers, leading to a fragmented discussion timeline and excessive alerts. This workflow is highly inefficient for comprehensive reviews.

• Mechanism: When you click "Add single comment," GitHub treats that feedback as a final, discrete event, triggering immediate email and UI notifications for everyone subscribed to the Pull Request.
• Under the Hood: Each single comment creates a separate entry in the PR timeline and triggers a distinct notification event, regardless of whether you plan to add more feedback moments later, leading to a 'notification flood.'
• Best Practice: Reserve single comments only for minor, non-critical suggestions or quick acknowledgments that do not require further batching or a formal review decision.

Key Takeaway: Avoid using single comments sequentially; they disrupt workflow and cause notification fatigue.

2. Starting a Pending Review Session

A structured review groups all line-level feedback into a single, draft session that remains hidden until explicitly submitted, preventing premature notifications. This is the foundation of non-disruptive review.

• Mechanism: The first time you leave a comment on a line and select 'Start a review,' GitHub automatically places that comment into a 'Pending' state, initiating the session.
• Execution Flow: All subsequent comments you leave on any file within that Pull Request are automatically added to this existing pending session, regardless of the file or line number.
• Under the Hood: The pending comments are stored temporarily as drafts associated with your user session and the specific PR ID; they are not written to the public timeline or database until the final submission action is taken.
• Best Practice: Always navigate to the 'Files changed' tab first and leave your first piece of feedback to ensure you initiate the batched review session immediately.

Key Takeaway: The pending state allows you to draft comprehensive feedback across multiple files before notifying the author once.

3. Consolidating Review Decisions

Submitting the review session consolidates all pending comments, attaches a high-level summary, and issues a definitive decision (Approve, Request Changes, or Comment), resulting in one coherent notification.

• Mechanism: Clicking 'Finish your review' opens a modal where you must select one of three required actions: 'Comment' (general feedback, no approval/rejection), 'Approve' (ready to merge), or 'Request changes' (blocking merge until addressed).
• Execution Flow: GitHub simultaneously publishes all pending line-level comments, posts the high-level summary comment, and records the formal decision on the PR timeline, triggering a single, comprehensive notification.
• Best Practice: Use the high-level summary box to provide context, praise, or a prioritized list of required changes, guiding the author on how to proceed with the feedback.

Key Takeaway: The final submission is a single, atomic event that delivers all feedback and the formal decision simultaneously.

Topics Covered in Pull Requests & Code Review

1. Locate Code Changes (0:30 - 0:36) — The first step in any review is navigating to the "files changed" tab to see the submitted differences.
2. Single Comment Anti-Pattern (0:36 - 1:13) — Demonstrating the inefficient workflow of adding feedback one comment at a time.
3. Notification Flood Explained (1:13 - 1:54) — Calculating how sequential, unbatched comments overwhelm the discussion timeline with alerts.
4. Initiate Pending Review (1:54 - 2:22) — Starting the proper structured review process by leaving the first comment which marks it as pending.
5. Batching Multiple Comments (2:22 - 2:34) — Adding subsequent feedback to the existing pending session across different lines and files.
6. Submit Final Decision (2:34 - 3:13) — Consolidating all batched feedback and issuing a formal decision like "Request changes."

Git Cheat Sheet

• files changed — Tab to locate all code differences
• Add single comment — Immediately notifies author of one piece of feedback
• Start a review — Initiates a pending, batched feedback session
• Add review comment — Adds feedback to the existing pending session
• Finish your review — Submits all pending comments and formal decision
• Request changes — Formal decision blocking merge until issues are resolved

Comparison Table

Common Pitfalls

• Mistake: Leaving sequential single comments for a full review. Avoid: Always initiate a review session for comprehensive feedback.
• Mistake: Forgetting to select a decision when finishing the review. Avoid: Ensure you choose Approve, Comment, or Request Changes in the final modal.
• Mistake: Reviewing code without navigating to the "files changed" tab first. Avoid: Use the "files changed" tab to ensure you see all submitted differences clearly.
• Mistake: Using the "Comment" decision when changes are mandatory. Avoid: Use "Request changes" to formally block the merge until issues are fixed.

FAQs

• What is a "notification flood"? It is the excessive volume of alerts generated when reviewers use sequential single comments, overwhelming the author and watchers with non-critical updates.
• Can I use a single comment if I only have one small typo fix? Yes, single comments are appropriate for minor, non-critical suggestions that do not require a formal review decision or batching.
• If I start a review, can I leave it and come back later? Yes, pending comments remain saved as drafts until you explicitly click "Finish your review" or discard the session.