What is a pull request? Anatomy of a PR page

A pull request is a proposal: “take the commits from my branch and merge them into that one”. Its page gathers everything the team needs to decide: the description, the discussion, the commits, the automated checks and the diff. GitLab calls the same thing a merge request (MR); only the name differs.

The most important fact sits in the header line: “Daniel wants to merge 2 commits into main from fix/checkout-button”. The branch after into is the base: the commits will land there. The branch after from is the compare branch: the commits come from it. GitHub also draws it as main ← fix/checkout-button.

The base isn't always main. A pull request can target another feature branch, or develop in teams that collect work there first. Merging it changes only that base branch; main and the live site stay as they were until a later merge carries the work further. When someone opens a pull request from the terminal, gh pr create --base main sets the same base.

A draft pull request says “work in progress, don't review yet”. Its badge is grey and reads Draft. GitHub won't merge a draft, whatever the reviews say: where the merge button would be, there's a Ready for review button instead.

Why open a pull request before the work is done? The team can see what's coming, the automated checks already run on every new commit, and nobody spends a review on half a fix. Daniel opens his drafts early on purpose.

When the author presses Ready for review, the badge turns green, Open, and the reviewers get their notification. It works backwards too: Convert to draft in the sidebar sends an open pull request back to draft, for example when the author finds a problem mid-review. From the terminal the same moves are gh pr create --draft, gh pr ready 136 and gh pr ready 136 --undo.

Draft or open, neither is merged yet. The badge only tells you whether the author wants reviews now.

Under the header, a pull request has four tabs (as of 2026), each with a counter. Pick the tab by the question you're asking.

• Conversation: the timeline. The description comes first, then comments, reviews, new commits and status changes in time order. The merge box sits at the bottom.
• Commits: the branch's own commits, step by step. Only the commits on the compare branch, not the ones main gained meanwhile. In a terminal, git log --oneline main..fix/checkout-button lists the same set.
• Checks: the automated runs, such as build, test and preview, with their logs.
• Files changed: the diff of the whole pull request. Every file it touches, removed lines in red, added lines in green, with a count per file. git diff --stat main...fix/checkout-button prints the same summary.

The file list is also a reviewer's first scope check. In #134, a bug fix for a button also touched styles/checkout.css: a file worth a question.

The description is the first comment on Conversation, and for a reviewer it's the most useful text on the page. A good one reads like a mini brief in four parts:

• What: the change in plain words.
• Why: the problem, with a link to its issue (Fixes #131).
• How to test: steps anyone can repeat, starting from the preview link.
• Screenshots: before and after, for anything customers see.

Many teams add a fifth part: what the change deliberately leaves out, so nobody reviews it for something it never promised.

What doesn't belong there: a list of every changed file (Files changed already has it) and pleas like “pls review asap”, which tell the reviewer nothing about the change. A weak description costs the author a meeting: three reviewers ask the same three questions, or nobody opens the pull request at all.

For a PM, the description is also where you check the scope: anything in the diff that the description doesn't mention deserves a question.

Before anyone reads the description, they see the title in a list of fifty pull requests. A good title says what changes and where: “Fix checkout button after cart edits”. “Checkout fixes” or “Daniel's branch” says nothing, and later the same title shows up in release notes and in the history of main, so it pays off twice.

To stop descriptions from starting as an empty box, teams keep a pull request template: a Markdown file in the repository, usually .github/pull_request_template.md. When anyone opens a new pull request, GitHub copies it into the description, so every pull request starts from the same headings: What, Why, How to test, Screenshots.

Lines inside <!-- --> are hints for the author; GitHub doesn't show them in the finished description. Filling the template takes two minutes, and the empty headings remind the author what reviewers will ask. GitLab has the same idea under the name merge request templates.

Fixes #131 in a description is more than a link. Fixes is a closing keyword: when the pull request is merged into the repository's default branch (at CatChow, main), GitHub closes issue #131 by itself.

Three verbs work, in any form: close, fix and resolve. So Closes #131, Fixed #131 and Resolves #131 all count. Each issue needs its own keyword: Fixes #131, fixes #132. Without a keyword, “#131” is only a reference: both pages mention each other, and nothing closes.

The sidebar confirms the link under Development: “Successfully merging this pull request may close these issues”, followed by #131 (GitHub's wording as of 2026).

Timing matters. Opening the pull request, an approval or leaving draft only connects the two pages; the issue stays open until the merge. And the keyword only acts on a merge into the default branch. At CatChow every merge into main is deployed within minutes, so support sees #131 close at about the time the fix goes live.

Closing keywords have one condition that's easy to miss: they act only when a pull request is merged into the default branch. That's the branch the repository opens on, usually main.

Some pull requests go somewhere else. A copy change can target feature/gift-wrap, the branch a bigger feature is being built on, and teams that work with a develop branch merge most pull requests there. Merge such a pull request, and its Closes #140 does nothing: the issue stays open, because the work hasn't reached the default branch yet.

That's actually the right behaviour. An issue should close when the fix is really in main, not when it is one step closer.

So when the base isn't the default branch, decide how the issue will close. Put the keyword in the pull request that finally carries the work into main, or close the issue by hand once that merge happens. Before you report anything as done, read the base in the header, then look at the issue's state.

The right-hand sidebar of a pull request answers “who and what for”:

• Reviewers: the people asked for a verdict. On #134, Oscar for the code and Sofia for the product side.
• Assignees: who is responsible for getting the pull request done, usually the author. Being assigned approves nothing.
• Labels: coloured tags for sorting and filtering, such as bug and checkout. They change no code and block nothing.
• Projects and Milestone: where the work sits in the team's plans.
• Development: the linked issue that a closing keyword will close.

Keep two kinds of rule apart. A rule is enforced by GitHub: at CatChow, main needs one approval, and until then the merge button simply stays blocked. A habit is enforced by the team: CatChow asks for two reviewers, an engineer for the code and a product person for anything customers will see. GitHub would accept one.

From a terminal, gh pr edit 134 --add-reviewer oscar --add-label bug sets the same fields.

Every time the author pushes a commit, checks run on it automatically. CatChow has three: build (does the site still build?), test (do the automated tests pass?) and preview. The first two are continuous integration, CI: robots that check every change. preview deploys the branch to a temporary copy of the site with its own link, so a PM can click through the change on a phone before any customer sees it.

Checks run on the branch, on its newest commit, not on the live site. The site keeps showing main. So a red test means “this change broke a test and needs another look”, not “customers can't check out”. A failure on an older commit stops mattering once a newer one passes. gh pr checks 134 prints the same list in a terminal.

At the bottom of Conversation, the merge box sums up whether the pull request can be merged: reviews, checks and conflicts. “Review required” plus “Merging is blocked” (GitHub's wording as of 2026) means the checks may be green, but nobody has approved yet.