Skip to content

Pull Requests

Opening and reviewing pull requests on GitHub — the collaboration workflow that powers open source.

What you'll learn

  • How to create a pull request from a feature branch
  • The PR review workflow: comments, approvals, and changes
  • Forking and contributing to repositories you do not own
  • Squash, merge, and rebase merge strategies on GitHub

Concept

What Is a Pull Request?

A pull request (PR) is a proposal to merge changes from one branch into another. It is the primary collaboration mechanism on GitHub, GitLab, and Bitbucket. Instead of pushing directly to main, you push to a feature branch and open a PR for review.

feature-branch → PR → review → merge → main

PRs are not a Git feature — they are a platform feature built on top of Git branches. The Git command is just git merge; the PR adds the review and discussion layer.

Creating a Pull Request

# Create and push a feature branch
git checkout -b feature-user-auth
# ... make changes ...
git add .
git commit -m "feat: add user authentication"
git push -u origin feature-user-auth

Then go to GitHub and click "Compare & pull request". Write a title and description, then click "Create pull request".

GitHub also offers a CLI:

gh pr create --title "Add user authentication" --body "Implements JWT-based auth"

The PR Description

A good PR description includes:

  • What — what does this PR do?
  • Why — why is this change needed? Link to the issue.
  • How — how did you implement it? Highlight key decisions.
  • Testing — how did you test it? What should the reviewer check?
  • Screenshots — for UI changes, before/after screenshots
## What
Adds JWT-based user authentication with login and logout endpoints.

## Why
Closes #42. Users currently cannot log in.

## How
- Added /api/login and /api/logout routes
- JWT tokens stored in httpOnly cookies
- Password hashing with bcrypt

## Testing
- [x] Unit tests for auth middleware
- [x] Integration test for login flow
- [ ] Manual test in staging

The Review Workflow

  1. Open the PR on GitHub
  2. Review — reviewers see the diff, can comment on specific lines
  3. Request changes — reviewer asks for modifications
  4. Update — push more commits to the feature branch (the PR updates automatically)
  5. Approve — reviewer approves the PR
  6. Merge — merge the PR into the target branch
  7. Delete the feature branch (GitHub offers this after merge)

Merge Strategies

GitHub offers three merge strategies:

  • Create a merge commit — preserves all commits + adds a merge commit (default)
  • Squash and merge — combines all feature commits into one commit on main
  • Rebase and merge — replays feature commits onto main without a merge commit

Squash merge is popular for keeping main's history clean — one commit per PR.

Forking Workflow

For repositories you do not have write access to (like open-source projects):

# 1. Fork the repo on GitHub (via the website)

# 2. Clone YOUR fork
git clone https://github.com/YOUR-username/project.git
cd project

# 3. Add the original repo as 'upstream'
git remote add upstream https://github.com/ORIGINAL-username/project.git

# 4. Create a feature branch
git checkout -b fix-typo

# 5. Make changes, commit, push to YOUR fork
git push -u origin fix-typo

# 6. Open a PR on GitHub from YOUR fork to the original repo

Keeping Your Fork Updated

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

Pull requests are where code quality is maintained through peer review. Always review PRs carefully — this is your last chance to catch bugs before they reach main.

Example

              # --- Standard PR workflow (you have write access) ---
git checkout -b feature-payment-integration
# ... implement the feature ...
git add .
git commit -m "feat: integrate Stripe payment gateway"
git push -u origin feature-payment-integration

# Open PR via GitHub CLI
gh pr create --title "Integrate Stripe payment" --body "Adds Stripe checkout and webhook handling."
gh pr view --web  # open the PR in your browser

# After review, push updates to the same branch
git commit -am "fix: address review feedback"
git push  # PR updates automatically

# Check PR status
gh pr status
gh pr checks  # view CI status

# Merge the PR (via CLI or GitHub website)
gh pr merge --squash  # squash merge
gh pr merge --merge   # merge commit
gh pr merge --rebase  # rebase merge

# --- Forking workflow (open source contribution) ---
git clone https://github.com/YOUR-username/repo.git
cd repo
git remote add upstream https://github.com/ORIGINAL-username/repo.git
git checkout -b fix-typo-in-readme
echo "fixed" >> README.md
git commit -am "docs: fix typo in README"
git push -u origin fix-typo-in-readme
# Now open a PR on GitHub from your fork to upstream

# Keep your fork's main in sync with upstream
git fetch upstream
git checkout main
git merge upstream/main
git push origin main
            

Shows the standard PR workflow with the GitHub CLI, pushing review updates, checking CI status, and all three merge strategies. Then covers the forking workflow for open-source contributions and keeping your fork synchronized with upstream.

Try it

Common mistakes

The mistake

Opening a PR with a huge, unfocused diff that is hard to review

The fix

Keep PRs small and focused on one concern. A 50-line PR gets reviewed quickly; a 5000-line PR gets rubber-stamped or ignored. If your feature is large, split it into multiple smaller PRs. Use feature branches and merge them incrementally.

The mistake

Not writing a PR description and making reviewers figure out the changes

The fix

Always write a clear PR description explaining what, why, and how. Link to relevant issues. Note what the reviewer should focus on. A good description speeds up review and improves code quality. Use the PR template if your repo has one.

Related Cheatsheets

Practice Pull Requests

3 exercises

Practice Pull Requests

Look up unfamiliar terms

A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.

View glossary

Build real projects

Apply what you learned by building guided projects with starter code and solutions.

View projects

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors