Pull Requests, Forks and Code Review on GitHub

A pull request (PR) is a way to say to your team: *I have finished some work on a branch. Please look at it, and if it is good, merge it into the main branch.* It is the central habit of working on GitHub. A pull request is a conversation around a set of changes, where people can comment on single lines, ask for changes and approve. Even if you work alone, the practice builds good habits. In a team, it is how mistakes are caught before they reach everyone.

The basic flow inside one repository

1. Update your main: git switch main, then git pull.
2. Create a branch for one task: git switch -c fix-footer-link.
3. Make small commits on the branch.
4. Push the branch: git push -u origin fix-footer-link. The first push prints a link to open a pull request, or GitHub shows a banner with a button when you open the repository page.
5. On GitHub, open the pull request. Choose main as the base and your branch as the one to compare. Write a clear title and description.
6. Teammates review the changes, comment and request improvements. You push more commits to the same branch, and the pull request updates itself.
7. When it is approved, someone merges it on GitHub. Then you delete the branch, switch to main and git pull to get the merged work.

Write a good pull request

• A short title that says what changed: Fix broken footer link on the contact page.
• A description that explains what and why: the problem, how you solved it, how to check it, and a screenshot if it is visual.
• Small size. A pull request with 50 lines gets a careful review. A pull request with 2,000 lines gets a quick glance and a thumbs-up. Split big work.
• Link the issue it solves. Writing Closes #12 in the description closes issue 12 when the pull request is merged.
• Check your own work first. Read the diff on the pull request page as if you were the reviewer.

Being reviewed and reviewing

• Read comments as help with the code, and not as criticism of you. Reply politely. If you agree, fix it. If you disagree, explain your reason.
• As a reviewer, be specific and kind. Say what you suggest and why. Praise good parts too.
• Look for: does it work, is it clear, are there tests, could it break something, are there secrets or private data in it?
• Mark questions as questions and suggestions as suggestions, so the author knows what is required.
• Do not approve what you did not read.

The three ways to merge

GitHub offers different buttons to merge a pull request, and a repository owner can choose which ones are allowed. A merge commit keeps all your commits and adds a merge commit. Squash and merge combines all the commits of the branch into a single one, which keeps the main history short. Rebase and merge replays your commits on top of main in a straight line. A beginner can use whatever the team chooses. Squash is popular for keeping a tidy history.

Forks: contributing to someone else's project

You usually cannot push to a project that belongs to someone else. Instead, you make your own copy on GitHub, a fork, and work there. Then you send a pull request from your fork back to the original project. The steps are these.

1. Click Fork on the project's page. GitHub creates a copy under your account.
2. Clone your fork: git clone https://github.com/yourname/project.git.
3. Add the original project as a second remote called upstream: git remote add upstream https://github.com/original-owner/project.git.
4. Create a branch, make your change and push it to your fork: git push -u origin my-change.
5. On GitHub, open a pull request from your branch to the original project, and follow its contribution rules, which are usually in a file called CONTRIBUTING.md.

Keep your fork up to date

git fetch upstream
git switch main
git merge upstream/main
git push origin main

Those four commands bring the original project's newest work into your fork's main branch. Do this before you start a new branch, so that you work from the current version.

Issues and other team tools

• Issues are tasks, bugs and ideas, with a discussion for each. Write a clear title and describe how to reproduce a bug.
• Labels such as bug or good first issue organise them. Many projects use good first issue for tasks suitable for newcomers.
• Checks: many projects run automatic tests when you open a pull request, and show a green tick or a red cross. Read the log of a red check, fix the problem and push again.
• Branch protection: owners can require reviews and passing checks before anything is merged into main. This protects the stable branch.

Your task

1. Make a practice repository on GitHub. Create a branch, change a file, push the branch and open a pull request into main.
2. Read the "Files changed" tab of your own pull request and leave one comment on a line, as a reviewer would.
3. Merge the pull request with the button, delete the branch, then update your local main with git pull.
4. Find a small open source project that you like, and read its CONTRIBUTING.md and the issues with the label good first issue. You do not have to contribute yet.

How to check it worked

• Your pull request shows the changes of your branch and can be merged.
• After merging, git pull on main brings in your change.
• You can explain what a fork is and when you need one.