Understanding Pull Requests

Pull Requests (PRs) are how you propose changes to a project. Learn how to create, review, and manage PRs professionally.

What You'll Learn

• What a pull request is
• How to create a PR
• Writing good PR descriptions
• The review process
• Responding to feedback
• Merging PRs

What is a Pull Request?

A Pull Request is a request to merge your branch into another branch (usually main).

Think of It Like...

Submitting an essay:

• You write it (make commits)
• Submit for review (create PR)
• Teacher gives feedback (code review)
• You revise (make changes)
• Teacher approves (PR approved)
• Essay accepted (PR merged)

Why Pull Requests?

Quality control:

• Someone reviews your code
• Catches bugs before they go live
• Ensures code meets standards

Knowledge sharing:

• Team learns from your approach
• You learn from their feedback
• Documentation of decisions

Collaboration:

• Discuss implementation
• Suggest improvements
• Build better software together

Creating a Pull Request

Prerequisites

Before creating PR:

1. ✅ Work on a branch (not main)
2. ✅ Code committed
3. ✅ Changes tested
4. ✅ Branch pushed to GitHub

Step 1: Push Your Branch

# First time pushing branch
git push -u origin feature/your-feature

# Subsequent pushes
git push

Step 2: Go to GitHub

Navigate to repository:

1. Open browser
2. Go to GitHub.com
3. Open your repository

GitHub will show:

Your recently pushed branches: feature/your-feature (Compare & pull request)

Step 3: Click "Compare & pull request"

Or manually:

1. Click "Pull requests" tab
2. Click "New pull request"
3. Select your branch

Step 4: Fill Out PR Form

Title (required):

Add contact form with validation

Description (recommended):

## Summary
Added a new contact form to the /contact page with:
- Email and message fields
- Client-side validation
- Success/error messaging

## Test Plan
- [x] Form displays correctly
- [x] Validation works (empty fields, invalid email)
- [x] Success message shows after submission
- [x] Tested on mobile and desktop
- [x] No console errors

## Screenshots
[Optional: Add screenshots of the feature]

Step 5: Create PR

Click "Create pull request"

PR is now open for review!

Writing Good PR Descriptions

Template

## Summary
Brief description of what this PR does

## Changes Made
- Bullet list of changes
- Keep it concise
- Focus on WHAT changed

## Why
Explain WHY you made these changes
- What problem does it solve?
- What feature does it add?

## Test Plan
- [x] How you tested
- [x] What scenarios you covered
- [x] What works

## Screenshots (if UI changes)
[Add images here]

## Notes
Any additional context, decisions made, or areas needing attention

Real Example

## Summary
Add dark mode toggle to user settings page

## Changes Made
- Add toggle switch component to settings UI
- Implement dark mode context provider
- Update all components to respect dark mode
- Add dark mode utility classes
- Persist preference to localStorage

## Why
Users requested dark mode for better viewing at night. This improves accessibility and user experience.

## Test Plan
- [x] Toggle switches between light and dark
- [x] Preference persists on page refresh
- [x] All pages render correctly in dark mode
- [x] Tested on Chrome, Safari, Firefox
- [x] Responsive on mobile

## Screenshots
(Light mode)
[image]

(Dark mode)
[image]

## Notes
- Used system preference as default
- Some third-party components don't fully support dark mode yet (documented in #123)

The Review Process

What Happens After Creating PR

1. Automated checks run:

   • Tests execute
   • Build verifies
   • Linters check code style

2. Team gets notified:

   • Reviewers see new PR
   • CI/CD status updates

3. Review begins:

   • Reviewers read code
   • Leave comments
   • Approve or request changes

Types of Feedback

Inline comments:

// Reviewer clicks line and comments:
"Consider using a more descriptive variable name here"

General comments:

"Great work overall! Just a few small suggestions."

Change requests:

"Please update the tests before merging"

Approvals:

"LGTM!" (Looks Good To Me)
"Approved ✅"

Responding to Feedback

Reading Comments

Types of comments:

• Suggestions: Optional improvements
• Questions: Reviewer wants clarification
• Required changes: Must fix before merge
• Nitpicks: Minor style/formatting issues
• Blocking: Critical issues preventing merge

Making Changes

If changes requested:

1. Make the edits in your local branch
2. Commit the changes:

git add .
git commit -m "Address review feedback: rename variables"

3. Push to same branch:

git push

4. PR updates automatically!

Responding to Comments

Reply to comments:

• Thank reviewer
• Explain your changes
• Ask clarifying questions if needed

Examples:

"Good catch! Updated in commit abc123."
"Done ✅"
"I renamed the variable to `userEmail` for clarity."
"Good point - I refactored this to use the utility function."

Resolving Conversations

After addressing feedback:

• Reviewer marks conversation as "Resolved"
• Or you can mark it (if you have permission)

PR Etiquette

As PR Author

Do:

• ✅ Keep PRs small (< 400 lines if possible)
• ✅ Write clear descriptions
• ✅ Respond to feedback promptly
• ✅ Test thoroughly before requesting review
• ✅ Be open to suggestions

Don't:

• ❌ Get defensive about feedback
• ❌ Ignore review comments
• ❌ Force push after review starts
• ❌ Merge your own PRs (usually)
• ❌ Make PRs with 1000+ line changes

As Reviewer

Do:

• ✅ Be constructive and kind
• ✅ Explain WHY when suggesting changes
• ✅ Approve when satisfied
• ✅ Point out good work too!

Don't:

• ❌ Be overly critical
• ❌ Nitpick minor style issues
• ❌ Leave comments without reviewing fully

Common PR Statuses

Draft PR

Mark as draft while still working:

• Can't be merged
• Signals "not ready for review"
• Useful for getting early feedback

To create:

• Click dropdown next to "Create pull request"
• Select "Create draft pull request"

Ready for Review

When done:

• Click "Ready for review"
• Reviewers get notified

Changes Requested

If reviewer asks for changes:

• PR status shows "Changes requested"
• Make edits and push
• Request review again

Approved

All reviewers approved:

• PR shows "Approved ✅"
• Ready to merge (if all checks pass)

Merged

After merge:

• PR closed automatically
• Changes now in target branch
• Branch can be deleted

Merging Pull Requests

Who Merges?

Depends on project rules:

• Sometimes: Author merges after approval
• Sometimes: Reviewer merges
• Sometimes: Maintainer merges

For K12worX: Usually maintainers merge

Merge Methods

Merge commit:

• All commits preserved
• Creates merge commit
• Full history retained

Squash and merge:

• All commits combined into one
• Cleaner history
• Loses individual commit messages

Rebase and merge:

• Commits replayed onto main
• Linear history
• No merge commit

Usually: Use squash and merge for PRs

After Merging

Clean up:

# Switch to main
git checkout main

# Pull latest (includes your merged PR)
git pull

# Delete feature branch locally
git branch -d feature/your-feature

# Delete on GitHub (usually automatic)
git push origin --delete feature/your-feature

Using GitHub CLI for PRs

Install gh CLI

Mac:

brew install gh

Windows:

winget install GitHub.cli

Create PR from Terminal

# Basic PR
gh pr create --title "Add contact form" --body "Description here"

# Interactive PR (asks questions)
gh pr create

# Draft PR
gh pr create --draft

View PRs

# List PRs
gh pr list

# View specific PR
gh pr view 123

# View in browser
gh pr view --web

Review from Terminal

# Checkout PR locally
gh pr checkout 123

# Test it
# ...

# Add review
gh pr review --approve

Common PR Scenarios

Scenario 1: Simple Feature PR

# Create and push
git checkout -b feature/add-search
# ... make changes ...
git add .
git commit -m "Add search functionality"
git push -u origin feature/add-search

# Create PR
gh pr create --title "Add search functionality"

# Wait for approval
# PR gets approved

# Merge (maintainer does this)
# Done!

Scenario 2: PR with Requested Changes

# Create PR
gh pr create

# Reviewer requests changes
# Make the changes
git add .
git commit -m "Address review feedback"
git push

# Request re-review
# (PR updates automatically)

# Get approved
# Merge

Scenario 3: Conflicting PR

# Your PR conflicts with main
# Update your branch
git checkout main
git pull
git checkout feature/your-feature
git merge main

# Resolve conflicts
# Test still works
git add .
git commit -m "Resolve merge conflicts"
git push

# PR updates, conflicts resolved

Troubleshooting PRs

"Merge conflicts"

Cause: Your branch and main changed same lines

Fix:

git checkout main
git pull
git checkout feature/your-feature
git merge main
# Resolve conflicts in files
git add .
git commit -m "Resolve conflicts"
git push

"Checks failing"

Cause: Tests or build failed

Fix:

1. Click "Details" to see error
2. Fix the issue locally
3. Commit and push
4. Checks re-run automatically

"Can't merge - requires approval"

Cause: Project requires review before merge

Fix: Wait for reviewer approval

"Branch out of date"

Cause: Main has new commits

Fix:

git checkout feature/your-feature
git merge main
git push

Quick Reference

Create PR:

# Push branch
git push -u origin feature/name

# Create PR (GitHub CLI)
gh pr create --title "Title" --body "Description"

# Or go to GitHub and click "Compare & pull request"

Update PR:

# Make changes
git add .
git commit -m "Address feedback"
git push
# PR updates automatically

View PRs:

gh pr list              # List all PRs
gh pr view 123          # View PR #123
gh pr view --web        # Open in browser

After merge:

git checkout main
git pull
git branch -d feature/name

What's Next

Congratulations! You've completed Chapter 07 and learned the Git workflow. Next, let's build more complex features:

Continue to Section 08: Advanced Topics →

---

Quick Links

• ← Making Commits
• Chapter 07 Overview
• Continue to Advanced Topics →