Pull requests, diffs, code review, and approval

A branch does not just slide into main.

Between “my feature works” and “it’s part of the product” stands the most important ritual in professional software. It is equal parts quality gate, teaching hospital, and book club.

This lesson walks the full ceremony: propose, diff, review, approve, merge.

What is a pull request?

A pull requestConcept · lights on your mappull requestThe request to land a branch in main, opened as a page on GitHub where the whole change can be read, discussed, and finally approved. The center of gravity of team engineering — most conversations about code happen on one. is a formal proposal: here is my branch. Please pull it into main. In conversation it is “PR,” always.

Mira finishes her retry fix, pushes her branch, and opens a PR on GitHub. The PR page assembles everything a teammate needs to judge the change:

• A title and description — what this change is, and why it exists
• The complete diff — every changed line, in every file
• A comment thread, where the review will happen
• Status indicators — approvals, and (after Module 12) the robots’ test results

A good description is craft, like a good commit message: what changed, why, and how it was tested. Reviewers arrive cold; the description is their briefing.

There is one naming note. GitLab calls the same object a merge request, the same ritual under a different label.

What is a diff?

What reviewers actually read is the diffConcept · lights on your mapdiffThe before-and-after of a change, shown as exactly the lines that vanished and the lines that appeared. Engineers read these the way editors read tracked changes — it is the day’s main reading material. — not the whole codebase, just what changed.

Removed lines carry a minus and read red, while added lines carry a plus and read green. You can read one right now:

The diff is why review scales. Instead of rereading a million-line codebase, a reviewer reads the two green lines and the one red one, in context.

What is code review?

Then comes code reviewConcept · lights on your mapcode reviewOther engineers examining a proposed change and questioning it before it may merge — the industry’s standing answer to “everyone makes mistakes.” Expect questions on your own PRs forever; seniority never graduates out of it.. Teammates read the diff and respond in comments.

On Mira’s PR, the comments might read:

• “What happens if order.id is null here?” — Module 3’s unhappy-path reflex, institutionalized
• “This duplicates the key logic in refunds, extract it?” — Module 3’s centralize-the-rule instinct
• “Can we add a test for the double-retry case?” — Module 12’s preoccupation, arriving early

Reviewers are broadly checking four things:

• Correctness — does it work, including the unhappy paths?
• Clarity — will the engineer of two years from now understand it?
• Consistency — does it match how this codebase does things?
• Safety — does it touch money, secrets, or personal data carefully?

Review is a conversation, not a verdict. Mira responds, answering questions and pushing new commits to the same branch, and the diff updates automatically. The cycle of comment, revise, re-review runs two or three rounds. That is routine.

Review is how a team teaches itself, and everyone gets reviewed, interns and principal engineers alike.

What is approval?

When the reviewers are satisfied, they grant approvalConcept · lights on your mapapprovalA reviewer’s recorded yes on a PR — and usually a hard gate, since branch protection counts approvals before it unlocks merging at all., the green check.

This is not a courtesy. Teams typically configure branch protection on main. The merge button physically does not work until the required approvals are in, often two of them. After Module 12, the automated tests must pass too. The always-clean main from last lesson is not kept clean by good intentions but by machinery.

The PR approved, Mira clicks merge. The branch folds into main, and the change stops belonging to Mira and starts belonging to everyone.

Why so much ceremony?

Three changed lines sit inside a multi-day ritual. Why? Because the PR is where four things happen at once:

• Bugs get caught while cheap. A null-crash found in review costs a comment. Found in production, it costs an incident.
• Knowledge spreads. Two reviewers now understand the payment retry logic. The one-engineer SPOF from Module 10 gets a little less single.
• Standards persist. The codebase stays one voice, not forty dialects.
• History gets documented. The PR’s discussion explains the change forever — future engineers read old PRs the way historians read letters.

The cost is real too. Review takes reviewer hours, and waiting for review is a drag on pace, so the standard mitigation loops back to last lesson: small PRs. A 50-line diff gets reviewed in an hour; an 800-line diff gets reviewed “tomorrow,” badly. Small branches, small PRs, and fast reviews are one culture with three benefits.

The mental model to remember

A pull request is the formal proposal to merge a branch into main, with title, description, diff, and discussion in one place.

A diff is the line-by-line change: minus lines out, plus lines in. Reviews read diffs, not codebases.

Code review is teammates checking the diff for correctness, clarity, consistency, and safety, with the author revising until the reviewers are satisfied. Everyone gets reviewed.

Approval is the sign-off that unlocks the merge, enforced by branch protection, not politeness.

The ceremony buys four things at once: cheap bug-catching, spreading knowledge, persistent standards, and documented history. Small PRs keep its cost low.

You should now be able to follow a change through the full social machine (propose, diff, review, revise, approve, merge) and explain why serious teams never skip it.