Pull requests and reviews
On This Lesson 11 topics
Lesson Overview
So far you have pushed straight to main. That is fine for a one-person practice project, and risky everywhere else. One mistaken push, and the shared copy that the whole team builds from is broken, with nobody having looked at the change.
A pull request (PR) is the fix. Instead of changing main directly, you push your work on a branch and then ask for it to be merged. In the shared-bookshelf picture, you do not slip pages into the album yourself: you leave your suggested pages on a side table with a note, others read them and comment, and the pages go into the album only once everybody is happy.
This lesson covers the whole round: open a PR, receive review comments, answer them, and merge. It builds on branches and merging from the previous module and on pushing a branch from the first lesson of this one. The screens on GitHub change over time, so button names below are the ones documented when this lesson was written.
Learning Objectives
By the end of this lesson you will be able to:
- Explain what a pull request is and why teams use it instead of pushing to
main. - Push a branch and open a PR with a clear title and description.
- Read a PR page: the Conversation, Commits, and Files changed tabs.
- Respond to review comments by pushing more commits to the same branch.
- Describe the three review outcomes: comment, approve, and request changes.
- Merge a PR and bring the result back to your own computer.
Written Explanation
What a pull request is
A pull request is a proposal to merge the commits of one branch into another, usually into main. The word "pull" comes from the maintainer's point of view: "please pull my changes into your branch". A PR is not a Git command; it is a feature of the hosting site. Git itself only knows branches and merges. GitHub adds a page around the merge where people can look at the diff, discuss, and approve before anything changes on the base branch.
A PR has two ends:
- The base branch: where the change should end up (usually
main). - The compare (or head) branch: the branch holding your commits.
The flow, step by step
- Start from an up-to-date
main:git switch mainthengit pull. - Create a branch for one small change:
git switch -c readme-typo. - Commit your change, as in the previous module.
- Push the branch and set its upstream:
git push -u origin readme-typo. - Open the PR. After a push, the repository's home page on GitHub usually shows a banner offering "Compare & pull request". Pick the base and compare branches, write a title and a description, and create it. You can also create a draft PR for work in progress: a draft cannot be merged until it is marked ready.
- Review. Others read your changes and leave feedback.
- Respond. Reply to comments and push more commits to the same branch.
- Merge when it is approved.
- Tidy up and update your own
main.
Writing a good title and description
The reviewer cannot read your mind, so tell them three things: what changed, why, and how to check it. A good title is a short sentence in the imperative mood, like a commit message: "Fix typo in README setup section", not "stuff". Keep each PR small and about one idea. A reviewer can judge twenty changed lines in minutes; two hundred files, almost never.
Title: Add deposit validation to Account
What: deposit() now rejects zero and negative amounts.
Why: the bank rules say a deposit must be positive.
How to check: run the tests; try deposit(-5) and read the message.Reviewing: the three outcomes
On the Files changed tab, a reviewer sees the diff, exactly like git diff from the earlier module. They can click on a line and write a line comment, then submit their review with one of three decisions:
| Decision | Meaning |
|---|---|
| Comment | General feedback, with no decision |
| Approve | The changes are ready to merge |
| Request changes | There is feedback you should address before merging |
A good review is specific and kind. It points to a line, explains the problem, and suggests a direction: "This loop stops one element early; can you check the condition?" Reviewing teaches you as much as being reviewed does: reading other people's code is a core skill.
Answering review comments
You do not close the PR and start over. You change the code on your same branch, commit, and push. Commits you add to the head branch become part of the same pull request, and the Conversation tab and the diff update. Reply to each comment (for example "Fixed in the last commit") so the reviewer can see what happened, then ask for another look. A PR can go through several rounds. Each round is cheap because the branch is small.
Merging
When the PR is approved, you (or a maintainer) merge it with the green button. GitHub offers three ways, depending on how the repository is configured:
- Merge commit: keeps all of the branch's commits and adds one merge commit.
- Squash and merge: combines the branch's commits into a single commit on the base branch.
- Rebase and merge: replays the commits onto the base branch, creating new commits.
For your first projects, the default merge commit is fine. You cannot merge a draft, and a repository may add its own requirements, such as approvals or passing automated checks. These are set with branch protection rules, which can require reviewed pull requests before anything reaches main and can block force pushes. For your own personal repositories you can switch such rules on yourself; where they are active, "push straight to main" is simply refused.
After merging, GitHub offers to delete the branch (some repositories do it automatically). On your computer you then update main and delete the local branch:
git switch main
git pull
git branch -d readme-typoTwo things to remember
A PR is a conversation about a branch, not a copy of it. And if the PR cannot merge cleanly because main moved on and the same lines changed, GitHub flags a conflict. You resolve it the way you learned in the previous module: bring main into your branch (git merge main or git pull), fix the files, commit, and push.
Examples
Example 1: open a PR for a one-line change (simple)
git switch main
git pull
git switch -c readme-typo
# fix one line in README.md
git commit -am "Fix typo in README"
git push -u origin readme-typoOn GitHub, the branch appears in the branch list, and the "Compare & pull request" banner shows. You choose base main, compare readme-typo, write the title "Fix typo in README", add a one-sentence description, and press Create pull request. The PR page shows your single commit and a diff with one line removed and one added.
Example 2: one review round (practical)
A teammate reads your PR and, on a line in the diff, writes: "Mention that the app also handles withdrawals." You fix it locally and push to the same branch:
git commit -am "Address review: mention withdrawals"
git push 2d5b14f..d820d90 readme-typo -> readme-typoNo -u and no new PR are needed: the branch already tracks the remote. The log of the branch now has two commits on top of the first, and both are in the PR:
d820d90 Address review: mention withdrawals
2d5b14f Describe the app
97d2a58 InitialYou reply to the comment on GitHub, "Done, see latest commit", and the reviewer approves.
Example 3: merge and clean up (realistic)
After approval you click the merge button. GitHub creates a merge commit on main with a message in the form "Merge pull request #1 from you/readme-typo". Your computer does not know yet. In a scratch run with a local stand-in for GitHub, the update looked like this:
git switch main
git pull
git branch -d readme-typo
git log --oneline --graphUpdating 97d2a58..6021704
Fast-forward
Deleted branch readme-typo (was d820d90).
* 6021704 Merge pull request #1 from you/readme-typo
|\
| * d820d90 Address review: mention withdrawals
| * 2d5b14f Describe the app
|/
* 97d2a58 InitialThe graph shows the shape of a PR: a short line of branch commits that rejoins main at the merge commit. If the repository had used squash and merge, you would see a single new commit on main instead, and the branch's commits would not appear in main's history. Which style a team uses is a team decision.
Backend Insight
On a backend team the PR is where several things happen at once. A teammate reads your code before it can affect production. Automated checks (tests, a build, a style check) run on your branch, and their results appear on the PR page. Decisions are recorded: months later, someone can open the PR and read why a rule was written the way it was.
That is why "do not push directly to main" is a rule almost everywhere. A backend service handles real money, data, and users, and main is usually what gets deployed. The PR gives a second pair of eyes, a place to run the tests, and a record. You will practice exactly this flow in the module lab, and every team workflow after it assumes it.
Common Mistakes
Mistake 1: Pushing directly to main
- Incorrect: committing on
mainand runninggit push, so no one reviews the change. - Correct: create a branch, push it, open a PR. Where possible, protect
mainso direct pushes are refused.
Mistake 2: Huge, unfocused pull requests
A PR that fixes a bug, renames files, and adds a feature is hard to review, so reviewers skim. Keep each PR about one idea.
Mistake 3: An empty or vague description
"Updates" tells the reviewer nothing. Write what, why, and how to check.
Mistake 4: Opening a new PR after each review comment
- Incorrect: closing the PR and opening another one with the fix.
- Correct: commit and push to the same branch; the open PR updates and the discussion stays in one place.
Mistake 5: Taking review comments personally, or replying with silence
A comment is about the code, not about you. Reply to every comment: either fix it, or explain politely why you disagree.
Exercises
Do the practice on a repository of your own; if you work alone, a second GitHub account or a partner can review.
Level A: Foundation
A1. In one sentence, what is a pull request?
Show solution A1
A1. A pull request is a request, made on the hosting site, to merge the commits of one branch into another, so that others can review the change first.
A2. What are the base and compare branches?
Show solution A2
A2. The base is the branch the change should be merged into (usually main). The compare (head) branch is the branch holding your new commits.
A3. Name the three review decisions and give one situation for each.
Show solution A3
A3. Comment: a reviewer has a question or a general remark but no verdict. Approve: the change is correct and ready to merge. Request changes: the reviewer found something that must be fixed first.
Level B: Application
B1. Write the sequence of commands from an up-to-date main to a pushed branch called add-usage that is ready for a PR.
Show solution B1
B1.
git switch main
git pull
git switch -c add-usage
# edit and test
git add README.md
git commit -m "Add usage section"
git push -u origin add-usageB2. A reviewer asks you to rename a variable on line 12. List what you do, in order, until the reviewer can see your fix.
Show solution B2
B2. Edit the file on the same branch, commit it (git commit -am "Rename variable"), run git push, and reply to the comment. The PR updates by itself.
B3. Write a good PR title and a three-line description for a change that makes withdraw reject amounts larger than the balance.
Show solution B3
B3. Title: "Reject withdrawals larger than the balance". Description example: "What: withdraw now throws an exception when the amount exceeds the balance. Why: accounts must not go negative. How to check: run the tests, then call withdraw(500) on an account holding 100."
Level C: Challenge
C1. Your PR page says the branch has conflicts with main. Explain why that can happen even though you never touched main, and give the steps to fix it.
Show solution C1
C1. Someone else's PR (or a direct push) changed the same lines on main after you branched, so Git cannot merge automatically. Fix: update your local main (git switch main, git pull), switch back to your branch, merge main into it (git merge main), edit the conflicted files, git add and git commit, then git push. The PR updates and the conflict warning disappears.
C2. A team lead wants no one, including themselves, to push to main directly. Which GitHub feature supports that, and what can it additionally require before merging?
Show solution C2
C2. Branch protection rules. They can require pull requests with a number of approving reviews and passing status checks before merging, and they block force pushes by default.
Mini Challenge
Make a tiny change in one of your projects, for example adding one line to the README. Do the full round: create a branch, push it, open a PR with a what/why/how description, ask a peer to leave one line comment, answer it with a new commit, get an approval, merge, and update your local main.
Check your work: the PR shows at least two commits, one conversation thread with a reply, the PR is merged, and git log --oneline --graph on your main shows the branch rejoining.
Summary & Next Lesson
Key takeaways
- A pull request proposes merging one branch into another and lets others review the change before it happens.
- Work on a branch, push it, open a PR with a clear title and a description of what, why, and how to check.
- Reviewers can comment, approve, or request changes. You respond by pushing more commits to the same branch.
- Keep PRs small, one idea each. Merge when approved, then update
mainand delete the finished branch. - Never push directly to
main; branch protection rules can enforce this.
Next lesson
Reviewers also read the project's front page. The next lesson, "Markdown and a good README", teaches the plain-text format GitHub renders and how to write a README that lets a stranger run your project.
Self-check
- What is the base branch of a PR?
- After a review comment, where do your extra commits go?
- What are the three review decisions?
- Why is pushing directly to
maindiscouraged? - What should the PR description tell the reviewer?
Show answers
- The branch the change will be merged into, usually
main. - Onto the same branch you opened the PR from; the PR updates.
- Comment, approve, and request changes.
- It skips review, so a mistake reaches the shared branch with nobody checking.
- What changed, why, and how to check it.
References
- GitHub Docs, About pull requests. Supports: a PR is a proposal to merge changes, discussed and checked before merging; the tabs; draft PRs cannot be merged.
- GitHub Docs, Creating a pull request. Supports: "Compare & pull request", base and compare branches, title and description, draft option, and that later commits to the head branch join the same PR.
- GitHub Docs, About pull request reviews. Supports: the Comment, Approve, and Request changes decisions.
- GitHub Docs, Merging a pull request. Supports: merge commit, squash, and rebase options, branch deletion after merge, requirements before merging.
- GitHub Docs, About protected branches. Supports: required reviews and status checks, force pushes blocked by default.
- Not verified from a fetched page: the PR title and description style advice is common team practice, not a GitHub rule. The merge output was produced locally with a simulated merge commit, not on GitHub.
Practice
Apply this lesson with the module's lab, exercises and quiz.
Marking a lesson complete is optional and you can undo it any time. Your progress stays in this browser.