Pull Requests and Code Review

Why teams do not push straight to main

On a real team, nobody commits directly to main. main is the version that is live, or about to be, so every change to it is proposed first, read by another person, and checked automatically before it goes in. The tool for that is the pull request, or PR.

A pull request is a page on GitHub that says: "I made these changes on my branch. Please review them and merge them into main." Despite the name, it is a request to pull your work in. It is also a conversation: reviewers comment on specific lines, you reply or change the code, and when everyone is happy the work is merged.

The whole workflow

1. Start from an up-to-date main
2. git switch -c fix/menu-typo        make a branch
3. edit, git add, git commit          small commits with good messages
4. git push -u origin fix/menu-typo   send the branch to GitHub
5. Open a pull request on GitHub      describe the change
6. Teammates review, you answer       comments, changes, approval
7. Merge the pull request             the work joins main
8. Delete the branch, git pull main   tidy up and start again

You already know steps 1 to 4 from the last lessons. Steps 5 to 8 happen on GitHub. This is the same loop on every company's team, from small startups to the biggest names.

Step 1 to 4: branch, commit and push

The first four steps in the terminal. Notice that a new branch needs -u the first time you push it:

git switch -c fix/menu-typo
# ...edit menu.txt...
git add menu.txt
git commit -m "Fix typo in the jollof rice name"
git push -u origin fix/menu-typo

Try it. The project below is already connected to a remote.

Step 5: open the pull request

After you push a branch, GitHub shows a yellow banner: Compare & pull request. Click it. (Or use Pull requests, then New pull request.) You will see:

• base: the branch you want to merge into (usually main).
• compare: your branch.
• A title and a description box. Writing these well is a real skill.
• The list of commits and the exact changes (the diff).

A good pull request

A template many teams use:

## What
Corrects the spelling of "Jollof rice" on the menu.

## Why
Customers noticed the typo. Fixes #12.

## How to test
1. Open menu.txt.
2. Check that the first line says "Jollof rice".

Writing Fixes #12 (or Closes #12) links the pull request to issue number 12, and GitHub closes that issue automatically when the PR is merged.

Step 6: review

A reviewer reads your diff on GitHub. They can:

• Comment on any line, ask a question, or suggest a change.
• Click Add a suggestion, which proposes exact replacement text that you can accept with one click.
• Finish with Approve, Comment or Request changes.

If they ask for changes, you do not open a new pull request. You commit more changes on the same branch and push, and the pull request updates itself.

Meanwhile, automatic checks (tests, linters and so on, run by a tool called GitHub Actions, which you meet in lesson 10) show green ticks or red crosses on the pull request. Many teams will not allow a merge until the checks pass and someone has approved it. This is called branch protection.

Being a good reviewer and author

• Be kind and specific. Comment on the code, not the person. "This could be simpler if we..." beats "This is wrong."
• Ask questions when you do not understand, because a confusing line is worth fixing.
• Say thank you and mark what you liked.
• As the author, do not take it personally. Review is how everyone gets better, including senior engineers.

Step 7: merging

When approved, you press Merge pull request. GitHub offers three ways:

Many teams use squash and merge so main has one clean commit per pull request. Follow your team's rule.

Step 8: tidy up

After merging, click Delete branch on GitHub. Then, on your computer:

git switch main
git pull
git branch -d fix/menu-typo

You are back on an up-to-date main, ready for the next task.

Contributing to other people's projects

For a repository you do not own, the workflow has one extra step at the start: fork it (your own copy on GitHub), clone your fork, work on a branch, push to your fork, and open a pull request from your fork to the original. This is how people contribute to open-source projects, and it is a great way to build a track record. Look for issues labelled good first issue.

Try it

First, do the branch, commit and push part of the workflow. The project is connected to GitHub.

Now write the pull request itself. This is the thing reviewers read first.