GitHub 10 🌐 Code Reviews, Comments, and Review Approvals - KandZ

⏱️ Estimated read: 10 min | |

A pull request opens a conversation, but a code review is the structured evaluation of the proposed changes. It is not just a place to leave comments; it is a workflow gate that determines whether code enters the main branch. GitHub provides specific tools for this: inline comments on specific lines, suggested changes that can be committed directly from the browser, formal reviews with approval or rejection states, and a requirement system that can block merges until specific reviewers sign off. Understanding these mechanics is the difference between a project that maintains quality and one where mistakes slip through.

Key point: A formal review is not the same as a comment. A comment is feedback; a review is a decision. Only an approval (or a requested change) satisfies the branch protection rules that block merges.

Why code reviews exist

The defect problem. A developer who wrote the code is blind to their own assumptions. A second pair of eyes catches logic errors, edge cases, and security flaws before they reach production. Studies consistently show that code review is the most effective defect-detection method available to software teams, outperforming testing for certain classes of bugs .

The knowledge-sharing problem. When code is merged without review, only the author understands it. When it is reviewed, at least one other person becomes familiar with the design, the trade-offs, and the location of the logic. This reduces the bus factor and makes future maintenance faster.

The standard enforcement problem. A codebase drifts without review. Naming conventions, architectural boundaries, and error-handling patterns degrade over time. A reviewer is the enforcement mechanism—not a compiler, which catches syntax errors, but a human who ensures that the code follows the project’s conventions and fits the existing architecture.

The asynchronous problem. Code review is not a meeting. The author submits a pull request and moves on to other work. The reviewer reads the diff, leaves comments, and submits a review when finished. This asynchronous model is what allows distributed teams to collaborate across time zones. GitHub’s review features are built for this: comments are threaded, suggested changes can be applied with a click, and the status is visible to everyone on the pull request.

The gate problem. A review that does not block a merge is just an opinion. Branch protection rules require a specific number of approvals before the merge button becomes active. This converts the review from a suggestion into a structural requirement. A pull request with a failing check or an unaddressed “Request changes” review cannot be merged, regardless of who clicks the button .

a. Inline comments and suggested changes

The “Files changed” tab is where reviewers spend most of their time. Hovering over a line number reveals a blue + icon. Clicking it opens a comment box attached to that specific line. The comment is visible to everyone, and the author can reply directly to it.

For simple fixes, the reviewer does not need to write a comment and ask the author to make the change. The reviewer can edit the code directly inside the GitHub comment box and click “Add suggestion to batch.” This creates a suggestion block that the author can apply with a single click of the “Commit suggestion” button.

1  fn process_data(data: &[u8]) {
2      let len = data.len();
3      if len == 0 { return; }
4      // ... rest of function
5  }

If the reviewer wants to suggest a modification to line 2, the suggestion block appears in the comment:

```suggestion
    let len = data.len().saturating_sub(1);
```

The author can accept the suggestion, which commits the change directly from the browser, or reject it and explain why. The suggested change does not require the author to pull the branch, edit the file locally, commit, and push—it happens entirely in GitHub.

b. Submitting a formal review

Leaving inline comments is not the same as submitting a review. To complete the review, the reviewer clicks “Review changes” in the top right corner of the “Files changed” tab. A dialog appears with a text field for a summary and three radio buttons: Comment, Approve, and Request changes.

Comment: Leaves feedback without explicitly approving or blocking the merge. This is useful for questions or observations, but it does not satisfy a branch protection rule that requires an approval.
Approve: Signals that the changes are ready to merge. This satisfies the approval requirement in branch protection.
Request changes: Signals that the pull request must not be merged until the feedback is addressed. The merge button is disabled.

The distinction is critical. A reviewer who leaves ten inline comments but selects “Comment” has not approved the pull request. A reviewer who selects “Request changes” has created a blocker. The author must address the feedback and, in most configurations, request a new review from the same person to clear the block.

c. Branch protection and required reviews

Branch protection rules are configured in the repository settings under “Branches.” For the main branch, a typical configuration requires a pull request before merging, at least one approval, and a passing status check. If “Require review from Code Owners” is enabled, the approval must come from someone listed in the CODEOWNERS file.

The CODEOWNERS file maps directories or file patterns to specific users or teams. When a pull request modifies a file matching a pattern, the corresponding code owner is automatically requested as a reviewer.

# .github/CODEOWNERS
*           @alex
/docs/      @alex @docs-team
*.rs        @backend-team

The protection rule ensures that changes to *.rs files cannot be merged without an approval from someone on the @backend-team. If the team has five members, any one of them can approve. The approval is recorded in the pull request timeline and counts toward the required number.

Without branch protection, reviews are advisory. The author can merge their own pull request, ignore “Request changes,” and bypass the entire process. The protection rule is what makes the review a gate.

Complete Example Session

# ============================================
# PART 1: OPEN A PULL REQUEST
# ============================================

# Author pushes a branch and creates a PR.
git push origin feature/auth
# PR: "Add token refresh rotation"

# ============================================
# PART 2: REVIEWER OPENS FILES CHANGED
# ============================================

# Navigate to the "Files changed" tab.
# The diff shows added, removed, and modified lines.

# ============================================
# PART 3: LEAVE AN INLINE COMMENT
# ============================================

# Hover over line 42, click the blue + icon.
# Comment: "This loop can run indefinitely if the token is malformed."

# ============================================
# PART 4: SUGGEST A CHANGE
# ============================================

# Hover over line 45, click the blue + icon.
# Click the suggestion button (document icon).
# Edit the suggested code.

```suggestion
    if token.len() != 64 { return Err(AuthError::Invalid); }
```

# ============================================
# PART 5: SUBMIT REQUEST CHANGES
# ============================================

# Click "Review changes" in the top right.
# Select "Request changes."
# Summary: "One logic fix needed before merge."
# Click "Submit review."

# ============================================
# PART 6: AUTHOR APPLIES SUGGESTION
# ============================================

# Author sees the suggestion in the PR.
# Clicks "Commit suggestion."
# GitHub commits the change directly to the branch.

# ============================================
# PART 7: RE-REQUEST REVIEW
# ============================================

# Author clicks the circular arrow next to the reviewer's name.
# A new review is requested.

# ============================================
# PART 8: REVIEWER APPROVES
# ============================================

# Reviewer opens "Files changed" again.
# Clicks "Review changes" → "Approve" → "Submit review."
# The merge button becomes active (if checks pass).

# ============================================
# PART 9: MERGE
# ============================================

# Author or maintainer clicks "Squash and merge."
# The PR is merged and the branch is deleted.

The nine parts trace the review workflow: opening a PR, inspecting the diff, leaving inline comments, suggesting a change, submitting a formal review, applying the suggestion, re-requesting review, approving, and merging.

Quick Reference

Review Outcomes

Outcome	Effect
Comment	Feedback without approval or block
Approve	Satisfies approval requirement
Request changes	Blocks merge until addressed

Branch Protection Settings

Setting	Effect
Require a pull request	Cannot push directly to branch
Require approvals	Merge blocked until N approvals
Dismiss stale reviews	Approvals reset on new commits
Require code owner review	Approval must come from CODEOWNERS

CODEOWNERS Syntax

Pattern	Meaning
`* @alex`	All files owned by @alex
`*.rs @backend-team`	Rust files owned by team
`/docs/ @docs-team`	Directory owned by team

Best Practices

✅ Do This:

```suggestion
    if token.len() != 64 { return Err(AuthError::Invalid); }

# ✅


```text
Review changes → Request changes
<!-- Block merge if a fix is required -->            # ✅

CODEOWNERS: *.rs @backend-team
<!-- Require domain experts to approve changes -->    # ✅

❌ Don’t Do This:

# Leave comments but select "Comment"
<!-- Does not satisfy approval requirement -->       # ❌

# Approve without reading the diff
<!-- Defeats the purpose of the gate -->             # ❌

# Ignore a "Request changes" review
<!-- Cannot merge until addressed -->               # ❌

Common Pitfalls

Pitfall	Why It Happens	Fix
Merge blocked despite approval	Stale review dismissed by new commit	Request new review after pushing
Code owner not auto-requested	`CODEOWNERS` file missing or invalid	Add file to `.github/CODEOWNERS`
Cannot merge own PR	Branch protection requires external approval	Request review from another user
Suggestion commit fails	Branch protection prevents direct commit	Use the “Commit suggestion” button (bypasses push)
Review status not visible	Review submitted as “Comment”	Submit as “Approve” or “Request changes”

Real-World Examples

1. Inline Comment

Line 42: "This loop can run indefinitely."

2. Suggested Change

```suggestion
return Err(AuthError::Invalid);


#### 3. Request Changes

```text
Review: Request changes — "Fix the loop bound."

4. Approve

Review: Approve — "Looks good."

5. CODEOWNERS File

*           @alex
/docs/      @docs-team
*.rs        @backend-team

6. Re-request Review

Click the circular arrow next to the reviewer.

7. Batch Suggestions

Add to batch → submit all suggestions at once.

8. Dismiss Stale Review

Branch protection: "Dismiss stale pull request approvals."

9. Require Code Owner

Branch protection: "Require review from Code Owners."

10. Check Review Status

Merge box: "1 approval, 0 requested changes."

Visual

Review Decision Flow

┌──────────────────────────────────────────────┐
│  Reviewer reads diff                         │
└──────────────────┬───────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│  Issues found?                               │
└──────────┬───────────────────────┬───────────┘
           │ YES                   │ NO
           ▼                       ▼
┌──────────────────────┐  ┌──────────────────────┐
│  Request changes     │  │  Approve             │
│  Merge disabled      │  │  Merge enabled       │
└──────────────────────┘  └──────────────────────┘
           │                       │
           ▼                       ▼
┌──────────────────────┐  ┌──────────────────────┐
│  Author fixes        │  │  Merge PR            │
│  Re-request review   │  │                      │
└──────────────────────┘  └──────────────────────┘

The “Request changes” state is the only blocker. “Comment” is neutral.

CODEOWNERS Routing

┌──────────────────────────────────────────────┐
│  Pull request modifies src/main.rs           │
└──────────────────┬───────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│  CODEOWNERS rule matches: *.rs @backend-team │
└──────────────────┬───────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│  @backend-team automatically requested       │
│  Branch protection requires their approval   │
└──────────────────┬───────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│  Merge blocked until approval                │
└──────────────────────────────────────────────┘

The code owner is not just a notification. The branch protection rule makes the approval mandatory.

Summary

Item	Value
Inline comment	Line-specific feedback
Suggested change	One-click fix applied via browser
Comment review	Neutral feedback, does not approve
Approve review	Satisfies approval requirement
Request changes	Blocks merge until addressed
Branch protection	Enforces approvals and checks
CODEOWNERS	Routes review requests by file path
Stale review	Approval dismissed on new commits

Key takeaways:

A comment is not a review. Only an “Approve” satisfies a branch protection rule that requires an approval. A “Comment” review is ignored by the gate .
Suggested changes are actionable feedback. The reviewer edits the code in the comment box, and the author commits the suggestion with one click.
“Request changes” is a hard block. The pull request cannot be merged until the author addresses the feedback and requests a new review.
CODEOWNERS assigns domain experts. Files matching the pattern require an approval from the listed user or team, enforced by branch protection .
Branch protection is the enforcement mechanism. Without it, reviews are advisory. The author can merge their own pull request and ignore requests for changes.
Stale reviews protect against silent merges. If the author pushes new commits after an approval, the branch protection setting can dismiss the approval, requiring a fresh review .

Remember: The review is the gate, not the comment. Inline comments and suggested changes are tools for communicating the required modifications. The formal review state—Approve or Request changes—is what actually blocks or permits the merge. A review that leaves a “Comment” has not approved the code; it has only discussed it.

Was this helpful?

Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!