Topic 34

Opening a Pull Request

Collaboration

You have pushed a branch. A pull request turns it into a proposal: here is what I changed, here is why, please look at it.

The mechanics take about a minute. Most of the actual work is writing a description that someone can act on without having to ask you questions.

Push the branch first

The branch has to exist on GitHub before it can be proposed

git push -u origin fix-meeting-time

Git prints a link in its output: GitHub notices the new branch and offers a direct URL for opening a pull request from it. That link is the fastest route, and it saves hunting for a button.

The two ends

A pull request has a direction: into main, from your branch. Same rule as merging in Chapter 6, expressed on a web page instead of by which branch you were standing on.

GitHub usually guesses correctly. Check anyway — a pull request pointed at the wrong branch is confusing to review and mildly embarrassing to fix.

Title and description

The title is a commit subject: short, imperative, specific. Everything from Chapter 2 applies, because it is read in exactly the same kind of list.

The description is where the work is. Three things belong in it:

What changed, in a sentence. Why, which is the part that saves the reviewer from having to ask. And what to check — the specific thing you would like a second pair of eyes on, which is the single most useful sentence you can write for a reviewer.

A description Theo can act on

The hall moved our meeting to Thursdays from September, so the
home page had the wrong day.

Changed the day in the header and in the footer summary — it
appears in both places, which is worth a second look in case I
missed a third.

For a visual change, a screenshot saves everyone five minutes. For a change to something you cannot see, say how you tested it.

The same change, proposed two ways

"fixes"

no reason · nothing to check · the reviewer has to ask before they can start

"Correct the meeting time to Thursday"

the hall moved · changed in header and footer · please check for a third occurrence

What the page shows

A pull request displays two things: every commit on the branch, and the combined diff of the whole change.

Reviewers use both. The combined diff answers "what does this do to the project"; the commit list answers "how did they get there". This is the practical reason Chapter 3 cared about commit size — a branch with three coherent commits reviews in minutes, and one enormous commit called "update" does not.

Drafts, and pushing more

GitHub lets you mark a pull request as a draft, which says "this is not ready, but you can see where I am going". A draft cannot be merged until you mark it ready, and marking it ready is what asks any code owners for their review. Useful for anything that will take more than an afternoon.

And the proposal is live rather than a snapshot: any commit you push to that branch appears on the pull request automatically. You never open a second pull request to fix something in the first one.

Responding to a comment is just another commit

git add index.html
git commit -m "Use the club's official wording for the meeting day"
git push

Common Confusions

"Opening a pull request merges my work." It proposes it. Nothing lands until somebody merges, which is two topics from now.
"I must not push again after opening it." Pushing more commits is exactly how you respond to review. The pull request updates itself.
"The description does not matter, the diff is right there." The diff shows what. The reviewer needs why, and needs to know where you are unsure. That is the same argument as commit messages, one level up.
"A draft pull request is a different kind of object." It is an ordinary pull request marked as not ready. It cannot be merged while it is a draft, and flipping it to ready is what requests review from any code owners.

Why It Matters

A pull request that explains itself gets reviewed in minutes; one that does not sits for days, and on a real team that is the difference between shipping and waiting.
"What to check" is the most useful sentence a beginner can learn to write, because it converts a vague request for approval into a specific task.
Branch, push, propose is the muscle memory your first job assumes you already have.

Knowledge Check

What does opening a pull request actually do?

It proposes the branch for merging and creates a page to discuss it
It merges the branch into main as soon as the checks have passed
It copies your branch into the main repository so others can commit to it
It locks the branch so that no further commits can change the proposal

Which sentence in a description is most useful to a reviewer?

The one saying what you would specifically like them to look at
The one listing every file that the change touches in the project
The one describing which commands you ran to make the change happen
The one promising that the change has been tested and is safe to merge

A reviewer asks for a change. What do you do?

Commit the fix and push it to the same branch the pull request came from
Close the pull request and open a new one with the corrected change
Edit the existing commit and force-push the corrected version to the branch
Reply explaining why the change is correct as it stands, then merge it

Why does a pull request show both the commit list and the combined diff?

Because they answer different questions: how you got there, and what it does
Because the combined diff is unreliable and the commits are used to verify it
Because GitHub cannot tell which one the reviewer prefers, so it offers both
Because the commit list is for the author and the diff is for the reviewer

You got correct