Pull Requests

Why it matters

Pull requests are how teams review and integrate code. They’re the gateway to contributing to open source and the standard for professional development.

Key concepts

• Fork — Personal copy of a repository on GitHub
• Pull Request — Request to merge your changes into another branch/repo
• Code Review — Process of examining code before merging
• Upstream — The original repository you forked from

The idea

The Proposal Analogy

A Pull Request is like a formal proposal:

1. Fork: Make your own copy of the project
2. Branch: Create a workspace for your changes
3. Develop: Make changes, commit
4. Push: Upload to your fork
5. PR: “Hey, I made something useful—want to pull it into the main project?”

Maintainers review your code, suggest changes, and eventually merge (or reject).

The Workflow

flowchart TD
    upstream["upstream (original)"]
    fork["your fork (origin)"]
    local["local clone"]
    branch["your fork / feature"]
    upstream -->|fork| fork
    fork -->|clone| local
    local -->|push| branch
    branch -->|pull request| upstream

Walkthrough

Fork Workflow

# 1. Fork on GitHub (click button)

# 2. Clone your fork
git clone git@github.com:YOUR-USERNAME/repo.git
cd repo

# 3. Add upstream remote
git remote add upstream git@github.com:ORIGINAL/repo.git

# 4. Create feature branch
git switch -c feature/awesome

# 5. Make changes, commit
git add .
git commit -m "Add awesome feature"

# 6. Push to your fork
git push -u origin feature/awesome

# 7. Open PR on GitHub

Staying in Sync with Upstream

# Fetch latest from upstream
git fetch upstream

# Update your main branch
git switch main
git merge upstream/main
git push origin main

# Rebase your feature branch
git switch feature/awesome
git rebase upstream/main
git push --force-with-lease origin feature/awesome

PR Best Practices

Title

feat: add user authentication
fix: resolve null pointer in checkout
docs: update installation guide

Description

## Summary
Brief description of changes.

## Changes
- Added login form
- Integrated OAuth2
- Added tests

## Testing
Describe how to test these changes.

Closes #123

Responding to Reviews

# Make requested changes
git add .
git commit -m "Address review feedback"
git push

# Or amend if it's minor
git add .
git commit --amend --no-edit
git push --force-with-lease

Key takeaways

• Fork → Branch → Commit → Push → PR
• Keep PRs focused and well-documented
• Respond to review feedback promptly
• Sync with upstream regularly

Dos & don’ts

✅ DO

• Write clear PR descriptions: Help reviewers understand your changes
• Keep PRs small: Easier to review, faster to merge
• Respond to feedback: Engage with reviewers constructively
• Test before opening PR: Don’t waste reviewers’ time on broken code

❌ DON’T

• Don’t open PRs without context: Include why, not just what
• Don’t force-push without warning: Reviewers lose their comments
• Don’t take feedback personally: Reviews improve code quality
• Don’t merge your own PRs: Get at least one approval

Going deeper

Conventional Commits: Many projects use prefixes: feat:, fix:, docs:, chore:, test:, refactor: These help auto-generate changelogs and semantic versions.

Draft PRs: Open a “Draft PR” for work-in-progress. Signals you want early feedback but aren’t ready for merge.

Common mistakes

“Close” vs “Refs”: Closes #123 auto-closes the issue on merge. Refs #123 links without closing. Be careful in commit messages—use Refs in commits, Closes in PR body only.

Merge conflicts in PRs: If main updated, your PR may have conflicts. Rebase locally, force-push, conflicts resolved.