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
- Open the PR on GitHub
- Review — reviewers see the diff, can comment on specific lines
- Request changes — reviewer asks for modifications
- Update — push more commits to the feature branch (the PR updates automatically)
- Approve — reviewer approves the PR
- Merge — merge the PR into the target branch
- 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
- CI/CD YAML Generator
PRs trigger CI checks — generate a pipeline that runs on PRs.
- SSH Key Generator
Set up SSH for pushing branches to open pull requests.
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 Resources
Related Cheatsheets
- Git Cheatsheet
PR workflow, forking, and merge strategies.
Practice Pull Requests
3 exercises
Look up unfamiliar terms
A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.
Build real projects
Apply what you learned by building guided projects with starter code and solutions.
Decode error messages
Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.