F6.3 · LESSON 3 OF 6

Pull requests

Use a remote, pull request and automated check to propose a reviewable change.

THE IDEA

A pull request is a conversation about a branch

A pull request (PR) says: "please merge the commits of this branch into that one". Git itself has no such object; it is a feature of the hosting service. What it adds is a page that shows the diff, a place for inline review comments, the result of automated checks, and a merge button governed by rules. Underneath, the merge is still an ordinary Git merge of ordinary commits.

OpenAdd two files #1

learner wants to merge 3 commits from feat into main

Adds one.txt and two.txt.

learner opened this pull request

✗ Required check 'test' failed.
✗ check test failed
• The base branch has 1 newer commit.

Merge commit Squash and merge Rebase and merge

A pull request page, simulated. Open the three tabs, then try the merge button while a rule blocks it.

What makes a pull request easy to review

A reviewer has minutes, not hours, and only your words to go on. Say the problem, show the behavior before and after with a concrete example, link the issue, and keep the diff to one change. A pull request that mixes a fix, a rename and a reformat cannot be judged as one thing.

A description that works

Problem: the calculator cannot subtract.

Before: calc.sub is undefined.
After:  sub(5, 3) returns 2.

Fixes #1

Predict first. Why does a before-and-after example belong in the description?

How the branch lands: three merge methods

The same pull request, merged three ways. The commits on the branch are the same; what main gets is not.

Merge commit: a new commit with two parents ties the branch in. Every original commit stays, and the branch shape is visible in history.

Reading main from the newest commit back: Merge pull request #1 from acme/feat , Main moves on , Add cart , Initial commit

Switch the method and compare the history. The branch label shows the original commits.

Chapter context

GitHub hosts repositories and adds collaboration around Git objects. A pull request is a review and discussion mechanism; the commits and branch history still follow Git rules.

TRY IT YOURSELF

Issue #1 asks for a sub function and a failing test already exists on main. main is protected: it needs a pull request, one approval and a passing test check. Use the terminal for Git, the panel for the (simulated) website. Edit with echo "text" >> file.

On a new branch, add a function named sub to src/calc.js that subtracts, and commit it. main must not move
Try to push straight to main. The protection rule must refuse (that is why pull requests exist)
Publish your branch to the server (but not to main)

learner@laptop

Type a command and press Enter. Tab completes names, ↑ recalls history.

learner@laptop:~/shop (main)$

Steps in the simulated website

○Open a pull request in the panel: a clear title, a description with Before and After, and a link to the issue
○Get the required check green. It runs the workflow on your branch automatically
○Ask Maya to review. She approves only a focused, explained, passing pull request
○Merge the pull request. The issue it fixes should close by itself

Open a pull request (simulated page)

Push a branch first. The form appears when the server has a branch other than main.

Your repository (0 ahead, 0 behind origin/main)

The server

Stuck? Try one of these

Stuck, or something not working? You can come back to it any time.

CHECK YOUR UNDERSTANDING

Why include a before-and-after example?

AIt makes the pull request longer, which looks more thorough to reviewers.BThe hosting service needs it before it will start the automated checks.CIt makes the intended behavior concrete and reviewable.

Chapter reference: math, worked example & code

This section belongs to the whole chapter, so it is the same on every lesson in it and may cover a different lesson's topic. The code for the experiment you just ran is inside the experiment itself.

Math and notation

For independent jobs with durations t1 and t2 running simultaneously, ideal elapsed time is max(t1,t2), excluding startup and queueing. A dependency adds a sequential edge and can make durations add instead.

Worked example

A build takes 3 minutes. Two test jobs taking 4 and 6 minutes start after the build and run together. The ideal critical path is 3 + max(4, 6) = 9 minutes, not 13. Real runners can add scheduling overhead.

Reference code

The following example uses the Python standard library and does not call a remote service.

build, tests = 3, [4, 6]
assert build + max(tests) == 9
assert build + sum(tests) == 13

Python examples are provided for study and local execution; this page does not execute Python.

Common mistakes

A green check is evidence for the checks that ran, not proof of every behavior. Forked code must not automatically receive trusted secrets.