Forking & Pull Requests

What Are Pull Requests?

A Pull Request (PR) is a proposal to merge changes from one branch into another. It's called a "pull" request because you're asking the maintainers to pull your changes into their repository.

Why Pull Requests?

• Code review: Others can review and improve your code before it's merged
• Discussion: Talk about implementation decisions
• Testing: Many projects run automated tests on PRs
• Documentation: PRs create a record of what changed and why
• Quality control: Prevents direct commits to main branches
• Learning: Great way to learn from feedback

The Fork and Pull Request Workflow

Here's the complete workflow for contributing to a project you don't own:

Original Repo → Fork (your copy) → Clone locally → Branch → Changes → Push → Pull Request
  (GitHub)        (GitHub)           (Your PC)      (Git)    (Code)   (Git)    (GitHub)

Let's walk through each step in detail.

Step-by-Step: Your First Pull Request

Step 1: Find a Project to Contribute To

For this tutorial, let's say you want to contribute to a project called awesome-project at github.com/maintainer/awesome-project.

Step 2: Fork the Repository

1. Go to github.com/maintainer/awesome-project
2. Click the "Fork" button (top-right)
3. GitHub creates a copy in your account: github.com/yourname/awesome-project

Step 3: Clone Your Fork

# Clone YOUR fork (not the original)
git clone https://github.com/yourname/awesome-project.git

# Navigate into it
cd awesome-project

Step 4: Add Upstream Remote

Add the original repository as "upstream" so you can get updates:

# Add the original repo as 'upstream'
git remote add upstream https://github.com/maintainer/awesome-project.git

# Verify your remotes
git remote -v

# You should see:
# origin    https://github.com/yourname/awesome-project.git (fetch)
# origin    https://github.com/yourname/awesome-project.git (push)
# upstream  https://github.com/maintainer/awesome-project.git (fetch)
# upstream  https://github.com/maintainer/awesome-project.git (push)

Step 5: Create a Feature Branch

Never work directly on main. Create a descriptive branch:

# Update main first
git checkout main
git pull upstream main

# Create feature branch
git checkout -b fix-typo-in-readme

# Or for a feature
git checkout -b add-dark-mode-toggle

Step 6: Make Your Changes

Edit files, write code, add features, fix bugs—whatever you're contributing:

# Make your changes
# ... edit files ...

# Check what changed
git status
git diff

# Stage and commit
git add .
git commit -m "Fix typo in installation instructions"

# Make more changes if needed
git commit -am "Add screenshot showing fixed section"

Step 7: Push to Your Fork

# Push your branch to YOUR fork
git push origin fix-typo-in-readme

# If first push, may need:
git push -u origin fix-typo-in-readme

Step 8: Create the Pull Request

1. Go to your fork on GitHub: github.com/yourname/awesome-project
2. You'll see a yellow banner saying "Compare & pull request"
3. Click "Compare & pull request"
4. You'll see a form with:
   • Title: Summary of your changes
   • Description: Details about what you changed and why
   • Base repository: Where you want to merge TO (the original)
   • Base branch: Usually main
   • Head repository: Your fork
   • Compare branch: Your feature branch
5. Fill in a good title and description
6. Click "Create pull request"

Writing a Great PR Description

A good PR description helps reviewers understand your changes quickly.

Good PR Template

## Summary
Brief description of what this PR does.

## Motivation
Why is this change needed? What problem does it solve?

## Changes Made
- Added X feature
- Fixed Y bug
- Updated Z documentation

## How to Test
1. Step 1
2. Step 2
3. Expected result

## Screenshots (if applicable)
![Before](before.png)
![After](after.png)

## Checklist
- [x] Tests pass
- [x] Documentation updated
- [x] No breaking changes
- [ ] Need feedback on approach

## Related Issues
Fixes #123
Related to #456

PR Title Best Practices

The PR Review Cycle

After creating your PR, here's what typically happens:

1. Automated Checks

Many projects run automated tests and checks on your PR:

• CI/CD tests: Unit tests, integration tests
• Linting: Code style checks
• Build verification: Ensure code compiles
• Security scans: Check for vulnerabilities

If checks fail, you'll see red X marks. Click them to see what went wrong.

2. Code Review

Maintainers and other contributors will review your code:

• Comments: Questions or suggestions on specific lines
• General feedback: Overall thoughts
• Requested changes: Things that must be fixed
• Approval: Code looks good!

3. Addressing Feedback

Respond to comments and make requested changes:

# Make the requested changes
# ... edit files ...

# Commit the changes
git add .
git commit -m "Address review feedback: improve error handling"

# Push to the same branch
git push origin fix-typo-in-readme

# The PR automatically updates!

4. Discussion and Iteration

You might go through several rounds of:

• Feedback → Changes → More feedback
• This is normal and healthy!
• Be patient and responsive
• Don't take feedback personally

5. Approval and Merge

Once reviewers approve:

• Maintainer clicks "Merge pull request"
• Your changes are merged into the main repository!
• Your contribution is now part of the project
• You might be listed as a contributor

6. After Merge

# Update your fork's main branch
git checkout main
git pull upstream main
git push origin main

# Delete your feature branch locally
git branch -d fix-typo-in-readme

# Delete it on GitHub
git push origin --delete fix-typo-in-readme

Responding to PR Feedback

Types of Feedback

1. Questions

Reviewer asks: "Why did you choose this approach?"

Good response: Explain your reasoning clearly and consider alternatives they might suggest.

2. Suggestions

Reviewer suggests: "Consider using Array.map() instead of a for loop here"

Good response: Either implement the suggestion or explain why your approach is better.

3. Required Changes

Reviewer requests: "Please add error handling here"

Good response: Make the change, push it, and comment that you've addressed it.

How to Respond Professionally

Example Responses

Good response to feedback:
"Thanks for the suggestion! I've updated the code to use Array.map() as you recommended. It's much cleaner this way. Let me know if you'd like any other changes!"

Good response to disagreement:
"I see your point about using a library here. I chose to implement it manually because:
1. It reduces dependencies
2. We only need this one feature
3. The implementation is straightforward

What do you think? I'm happy to reconsider if you feel the library is still better."

Good response to question:
"Great question! I used this approach because the API documentation recommends it for rate-limited endpoints. Here's the link: [url]. However, if there's a better way, I'm all ears!"

Keeping Your Fork Updated

The original repository changes while you're working. Keep your fork synchronized:

Regular Sync Routine

# Switch to main
git checkout main

# Fetch from upstream
git fetch upstream

# Merge upstream changes
git merge upstream/main

# Push to your fork
git push origin main

Update Your Feature Branch

If the main branch changed while you were working:

# Update main first
git checkout main
git pull upstream main

# Switch to your feature branch
git checkout fix-typo-in-readme

# Merge main into your branch
git merge main

# Or rebase (cleaner history)
git rebase main

# Push updated branch
git push origin fix-typo-in-readme --force-with-lease

Draft Pull Requests

GitHub lets you create Draft Pull Requests for work-in-progress:

When to Use Drafts

• Get early feedback on your approach
• Show progress on long-running features
• Discuss design decisions before finishing
• Signal that code isn't ready for full review

Creating a Draft PR

1. When creating the PR, click the dropdown on the button
2. Select "Create draft pull request"
3. When ready, click "Ready for review" to convert to a normal PR

Pull Request Etiquette

Before Creating a PR

• Read CONTRIBUTING.md: Follow project guidelines
• Check existing PRs: Make sure someone isn't already working on it
• Test your changes: Ensure everything works
• Follow code style: Match the project's style
• Keep it focused: One PR = one feature/fix

While PR is Open

• Respond promptly: Don't ghost reviewers
• Be patient: Maintainers are often volunteers
• Stay engaged: Participate in discussion
• Don't force merge: Wait for approval

What Makes a Good PR

Practice Fork/PR Commands

Try these commands to practice the fork workflow:

Troubleshooting PRs

Issue: PR Shows Conflicts

# Update main
git checkout main
git pull upstream main

# Switch to your branch
git checkout your-branch

# Merge main into your branch
git merge main

# Resolve conflicts (we'll learn this in detail next lesson)
# Then:
git add .
git commit
git push origin your-branch

Issue: Pushed to Wrong Branch

# Create branch from current commit
git branch fix-feature

# Reset main
git checkout main
git reset --hard upstream/main

# Switch to fix branch
git checkout fix-feature
git push -u origin fix-feature

Issue: Want to Change PR Branch

Command Reference

Here's a quick reference for the fork workflow:

# Initial Setup
git clone https://github.com/yourname/repo.git
git remote add upstream https://github.com/original/repo.git
git remote -v

# Starting New Work
git checkout main
git pull upstream main
git push origin main
git checkout -b feature-name

# Making Changes
git add .
git commit -m "Description of changes"
git push -u origin feature-name

# Syncing with Upstream
git fetch upstream
git checkout main
git merge upstream/main
git push origin main

# Updating Your PR Branch
git checkout feature-name
git merge main  # or: git rebase main
git push origin feature-name

# After PR is Merged
git checkout main
git pull upstream main
git push origin main
git branch -d feature-name
git push origin --delete feature-name

Key Takeaways

What's Next?

Excellent work! You now understand the complete fork and pull request workflow. You can contribute to any project on GitHub—from small open source tools to major frameworks!

In the next lesson, we'll explore Code Review Basics. You'll learn how to review other people's pull requests, give constructive feedback, understand what to look for during reviews, and become a better collaborator. Code review is a critical skill that improves both your own code and your ability to help others!