AlgoInsight

Free lesson · Git Mastery

What is A Pull Request

Medium6 min readgit

What Is a Pull Request

A note from Brandon Carter, Principal SDE at AWS S3 and Head of Curriculum.

The Mechanism That Reviews Live On

A pull request - PR - is a request for a maintainer to integrate a proposed change into a target branch. It's the unit of code review in modern Git workflows. Engineers create branches, do work, push the branches, and open PRs proposing the work for review and integration.

Importantly, pull requests aren't a Git feature. Git itself doesn't have a concept of a pull request - the term comes from git request-pull, an old command that produced a textual summary of a branch suitable for emailing to maintainers. The modern PR - with its web UI, inline comments, automated checks, approval workflows - is a feature of the hosting platform (GitHub, GitLab, Bitbucket, Azure DevOps, internal tools at large companies). Different platforms have different specifics; the conceptual model is shared.

At AWS S3, the PR is where the work of code review happens. As an Amazon Bar Raiser, I've conducted over 300 interviews, but a much larger share of my professional time has been spent in code review. The PR is the artifact that makes review possible - it bundles the change, provides space for discussion, and tracks the approval state.

This topic covers what a PR is conceptually, what the platforms do with them, and why they've become the universal mechanism.

The Anatomy of a PR

A PR has a few core elements:

Source. The branch (and repository, in forking workflows) containing the proposed changes.

Target. The branch the changes would be merged into.

Description. A written explanation of what the change does and why.

Diff. The platform shows the difference between the source and target - what would be added if the merge happened.

Discussion. Threaded comments - overall PR comments and inline comments on specific lines of code.

Reviews. Formal sign-offs (approval, request changes, comment) from reviewers.

Status checks. Automated checks (CI results, security scans, linting) that report success or failure.

Decision. Whether the PR has been merged, closed without merging, or is still in progress.

The PR bundles all these elements into a single trackable unit. The combination of code change, written context, discussion, and approval state is what makes review effective. Without the PR mechanism, each element would be scattered across different tools - chat for discussion, diff tools for review, ad-hoc tracking for approval state. The PR puts them in one place.

What a PR Is, Mechanically

When you open a PR, the platform creates a record that references two things:

  1. The current tip of the source branch (a specific commit hash)
  2. The current tip of the target branch (a specific commit hash)

The platform computes the diff between them and presents it for review. As you push new commits to the source branch, the PR updates - the new diff is recalculated.

This is important: the PR isn't a static snapshot. It tracks the live state of the source branch. Reviewers can see the latest state by visiting the PR. Past states are recorded as "review rounds" or in the commit history.

# Open a PR after pushing the branch
git push -u origin feature/new-replication
# Then via the platform UI: open PR from feature/new-replication to main

# Update the PR by pushing more commits
git commit -m "Address review comments"
git push
# PR automatically updates to show the new state

The push updates the PR. There's no separate "update PR" command. The platform watches the source branch and refreshes the PR's view whenever new commits arrive. This is why some teams say "the PR is the branch" - the conceptual model treats them as the same object viewed from different angles.

What Different Platforms Call Them

The naming varies:

The conceptual model is the same; the names differ. "Pull request" is the most common; "merge request" is technically more accurate (the PR is asking for a merge, not for a pull); the difference doesn't matter in practice.

I'll use "PR" throughout this module. Adjust the terminology to your platform if needed.

Why PRs Took Over

Before PRs, code review happened in various ways:

Email patches. The Linux kernel still uses this model. Patches are emailed to a maintainer who reviews and applies them. Works for high-trust experienced contributors; doesn't scale to broader teams.

Diff tools. Engineers would generate diffs and share them via various ad-hoc mechanisms - file sharing, code review tools like Crucible. Worked but required manual coordination.

No review. Some teams just pushed directly to shared branches. The "review" happened after the fact, if at all.

PRs replaced these because they bundled the review with the change in one trackable unit. The same UI shows the code, the discussion, the approval state, and the integration step. Engineers don't have to coordinate across multiple tools.

The convenience drove adoption. GitHub popularized the model around 2008-2010; GitLab and others followed. Within a few years, PRs became the universal default for modern engineering teams.

A Specific Pattern at AWS S3

The team's PR conventions:

The rules are enforced by the platform, not just by convention. Engineers can't bypass them in normal work. The combination of clear rules and automated enforcement is what makes the team's review discipline reliable. Topic 20.3 covers branch protection in depth.

The pattern combines social discipline (the conventions about what reviews look like) with technical enforcement (branch protection rules). Either alone is fragile; the combination is robust.

A Specific Story From Stripe

At Stripe in 2018, I joined a team that had a strong review culture but inconsistent PR discipline. Some PRs had thorough descriptions; some had one-word descriptions. Some had clear linked tickets; some referenced verbal conversations only. The review quality varied accordingly - when the PR was clear, review was effective; when the PR was opaque, reviewers had to ask basic questions to understand what was happening.

The fix was a PR template - a markdown form that opened automatically when creating a PR. The template asked for:

Within two weeks of adopting the template, PR quality became consistent. Reviewers spent less time understanding context; more time on the actual review. Topic 12.7 covers PR templates in depth.

The lesson: the PR mechanism is the same across teams. What differs is the discipline around using it. Small structural changes - like templates - can dramatically affect the quality of the review process.

When PRs Are Optional

In some workflows, PRs are optional:

For everything else, PRs are essentially required. The benefit of catching issues before they land outweighs the cost of the review step.

What Comes Next

Topic 12.2 covers creating a PR - the mechanics across platforms. Topic 12.3 covers code review fundamentals - what good review looks like. Topic 12.4 covers reviewing others' code in depth. Topic 12.5 covers responding to review comments. Topic 12.6 covers merging. Topic 12.7 covers PR templates. Topic 12.8 covers stacked PRs.

What Goes Wrong

Warning: Common PR misconceptions:

Thinking PRs are a Git feature. They're a platform feature; Git itself doesn't have them.

Treating the PR as separate from the branch. They track each other; the PR updates as the branch updates.

Confusing PR approval with merge. Approval is a state; merge is the action. They're related but distinct.

Opening PRs without descriptions. Forces reviewers to reconstruct context.

Mixing different platforms' terminology. Be consistent within a team.

Skipping PRs for "small" changes. Small changes can break things too.

Try It

Exercise: Build the mental model:

  1. Open an existing PR in your team's repository. Look at every element - description, diff, comments, checks, approvals.
  2. Identify which platform your team uses. Read its documentation for any features you don't know.
  3. Look at a PR with many review comments. Note how the discussion is structured.
  4. Look at a PR that was closed without merging. Understand why.
  5. Open a small PR yourself. Pay attention to each step of the creation flow.
  6. Review your team's PR conventions - are they documented?

Back to Git Mastery