Pull Requests and Team Workflow

Why Not Just Push to main?
The GitHub Flow
Start with an Issue
Push a Feature Branch
Open a Pull Request
Reviewing a Pull Request
Merge and Clean Up
Working with Teammates
Forks: Contributing to Other People's Projects
Try It Yourself

1. Why Not Just Push to main?

So far you've pushed straight to main. On a team, that's risky:

A mistake goes straight into the version everyone uses.
Nobody else sees the change until it's already there.
There's no place to discuss whether or how to make a change.

A pull request (PR) fixes all three. Instead of pushing to main, you push a branch and ask: "Please review these changes and merge them into main." Teammates read the diff, leave comments, and approve it. Only then does it get merged.

On almost every professional team, all changes to main go through pull requests — even small ones, even from senior developers.

2. The GitHub Flow

Here's the whole workflow you'll practise in this chapter. It's called the GitHub flow, and it's the most common way teams work:

1. Issue        describe the work          (on GitHub)
2. Branch       git switch -c add-projects  (on your computer)
3. Commit       small, focused commits
4. Push         git push -u origin add-projects
5. Pull request ask for review              (on GitHub)
6. Review       discuss, fix, push again
7. Merge        into main                   (on GitHub)
8. Clean up     pull main, delete branch    (on your computer)

You already know steps 2–4. The new parts happen on GitHub.

3. Start with an Issue

An issue is a task, bug report, or idea, written down on GitHub so it isn't forgotten. In your my-site repository, open the Issues tab → New issue:

Title: Add a projects section to the home page
Description: List the things I've built, starting with this site.

Click Create. GitHub gives it a number — #1 for your first one. Issues are your project's to-do list, and on a team they're how work gets assigned and discussed before anyone writes code.

4. Push a Feature Branch

In ~/my-site, start from an up-to-date main and create a branch for the issue:

cd ~/my-site
git switch main
git pull
git switch -c add-projects

Add a projects section to index.html, just above the About link:

    <h2>Projects</h2>
    <ul>
      <li>my-site — this website, built with Git and GitHub</li>
    </ul>

Commit, then push the branch to GitHub:

git commit -am "Add projects section to home page"
git push -u origin add-projects

...
remote: Create a pull request for 'add-projects' on GitHub by visiting:
remote:      https://github.com/dara-sok/my-site/pull/new/add-projects
remote:
To https://github.com/dara-sok/my-site.git
 * [new branch]      add-projects -> add-projects
branch 'add-projects' set up to track 'origin/add-projects'.

GitHub now has the branch. main on GitHub hasn't changed at all.

5. Open a Pull Request

Open your repository on GitHub. A yellow banner appears: add-projects had recent pushes with a Compare & pull request button. Click it. (You can also use the link from the push output, or the Pull requests tab → New pull request.)

Check the top of the form: base: main ← compare: add-projects. That reads "merge add-projects into main".

Fill in:

Title: a clear summary, like a commit message — Add projects section to home page
Description: what the change does and why, plus anything a reviewer should check. End it with:

Closes #1

Writing Closes #1 links the PR to the issue. When the PR is merged, GitHub closes the issue automatically.

Click Create pull request. Your PR has three tabs worth knowing:

Conversation — the description, comments, and status
Commits — the commits on the branch
Files changed — the full diff, the same one git diff shows

A PR follows its branch. If you push more commits to add-projects, they appear in the PR automatically — that's how you respond to review feedback.

6. Reviewing a Pull Request

Reviewing is where teams catch bugs and share knowledge. Open Files changed:

Hover over any line and click the blue + to leave a comment on that exact line — a question, a suggestion, or a typo.
When you're done, click Review changes and choose:
- Comment — general feedback, no decision
- Approve — looks good, ready to merge
- Request changes — needs fixes before merging

GitHub won't let you approve your own PR, so when you're working alone, just leave yourself a comment to try it out. Then respond to it the way a real author would: make the fix locally, commit, and git push. Watch the new commit appear in the PR.

Good review habits, on both sides:

Keep PRs small. A 50-line PR gets a careful review; a 2,000-line PR gets "looks good to me".
Review the code, not the person. "This could break on mobile — what about…?" rather than "You did this wrong."
Explain why. In the description as the author, and in comments as the reviewer.
Say what's good, too. Reviews aren't only for problems.

7. Merge and Clean Up

When the PR is approved (or, for now, when you're happy with it), click Merge pull request → Confirm merge.

The button has a dropdown with three options. Create a merge commit is the default and works exactly like the merges you've done in the terminal — use it for this series. You'll also see Squash and merge (combine all the branch's commits into one) and Rebase and merge; many teams prefer one of those, and they'll tell you which.

After merging:

Issue #1 closes automatically, thanks to Closes #1.
GitHub offers a Delete branch button. Click it — the branch's work is in main now.

Your computer doesn't know about any of this yet. Clean up locally:

git switch main
git pull
git branch -d add-projects
git fetch --prune

git pull brings down the merge. git branch -d deletes your local branch. git fetch --prune removes origin/add-projects, the leftover memory of the branch you deleted on GitHub.

That's one full lap of the GitHub flow. On a team, you'll do this every day.

8. Working with Teammates

To let a friend push branches to your repository, go to Settings → Collaborators → Add people, and invite them by username. Once they accept, they can clone the repository, push branches, open PRs, and review yours.

Teams usually also protect main: under Settings → Rules (or Branches on some plans) you can require that every change to main comes through a pull request with at least one approval. That turns "please don't push to main" from a polite request into a rule.

If you have the GitHub CLI from chapter 8, a few commands save trips to the browser:

gh pr create        # open a PR for the current branch
gh pr list          # list open PRs
gh pr checkout 12   # download PR #12 to test it locally
gh issue list       # list open issues

9. Forks: Contributing to Other People's Projects

You can't push branches to a repository you don't have access to — an open-source project, say. Instead you fork it: click Fork on the project's page, and GitHub makes a full copy under your own account.

The flow is then almost the same:

Fork the project on GitHub.
Clone your fork: git clone https://github.com/<you>/<project>.git
Branch, commit, and push to your fork, as usual.
Open a pull request from your fork's branch to the original project. GitHub offers this automatically after you push.
The project's maintainers review it and, if they like it, merge it.

That's how anyone in the world can contribute to projects like Git, Next.js, or VS Code. Many projects label easy starter tasks with good first issue — a great way to make your first real contribution.

10. Try It Yourself

Open an issue in my-site for the projects section.
Do the full GitHub flow: branch, commit, push, open a PR that says Closes #1, merge it, delete the branch, and clean up locally. Check that the issue closed itself.
Respond to review. Open a second PR (for example, add a Contact link to the home page). Leave a line comment on it, push a fix commit, and watch the PR update before merging.
Invite a friend as a collaborator and review each other's PRs.
Look at a real project's PRs. Open github.com/vercel/next.js/pulls, open any pull request, and read the Conversation and Files changed tabs. Real teams work exactly the way you just did.

Next, let's put everything together and publish my-site on the internet.