Your First Pull Request: A Step-by-Step Guide

So you've found a bug to fix or a feature to add, and you're ready to contribute. But how do you actually get your code from your computer into someone else's project? Let me walk you through creating your very first Pull Request (PR).

Before You Start: Understanding the Workflow

A Pull Request is your way of saying: "Hey, I made some improvements to your code—want to merge them in?" It's called a "pull request" because you're asking the maintainers to pull your changes into their project.

The basic flow looks like this:

1. Get a copy of the code
2. Make your changes in a separate branch
3. Push your changes
4. Open a PR
5. Respond to feedback
6. Celebrate when it's merged! 🎉

Step 1: Getting the Code

The first step depends on whether you're working with a public or private repository.

For Public Repositories (Most Open Source Projects)

Fork the repository first. A fork is your own copy of the project on GitHub.

1. Go to the repository on GitHub
2. Click the "Fork" button in the top-right corner
3. GitHub creates a copy under your account (like yourname/project-name)

Then clone your fork to your computer:

git clone https://github.com/YOUR-USERNAME/project-name.git
cd project-name

For Private Repositories (Your Team/Company Projects)

Just clone directly since you already have access:

git clone https://github.com/company/project-name.git
cd project-name

Step 2: Set Up Your Remote (For Forked Repos Only)

If you forked the repo, add the original repository as a remote called "upstream". This lets you sync with the latest changes:

git remote add upstream https://github.com/ORIGINAL-OWNER/project-name.git

Verify your remotes:

git remote -v
# origin    https://github.com/YOUR-USERNAME/project-name.git (your fork)
# upstream  https://github.com/ORIGINAL-OWNER/project-name.git (original)

Step 3: Create a Branch

git checkout -b feature/landing-page

Branch Naming Conventions

Good branch names are descriptive and follow project conventions:

# Features
git checkout -b feature/user-authentication
git checkout -b feature/add-dark-mode

# Bug fixes
git checkout -b fix/login-button-alignment
git checkout -b bugfix/null-pointer-exception

# Documentation
git checkout -b docs/api-documentation
git checkout -b docs/update-readme

# Refactoring
git checkout -b refactor/database-queries

Some projects use issue numbers:

git checkout -b fix/issue-247-password-validation
git checkout -b 247-password-validation

Step 4: Make Your Changes

Now do your actual work—write code, fix bugs, update documentation. Here's where the magic happens!

Before You Commit: A Checklist

• [ ] Does your code work? Test it locally
• [ ] Does it follow the project's style? Check for linters or formatting tools
• [ ] Did you write/update tests? Most projects require tests
• [ ] Did you update documentation? If you changed behavior, update the docs
• [ ] Did you test edge cases? Don't just test the happy path

Step 5: Commit Your Changes

Stage your changes:

git add .
# Or add specific files
git add src/components/LandingPage.jsx
git add README.md

Commit with a clear message:

git commit -m "feat: add responsive landing page with hero section"

Writing Good Commit Messages

Your commit message should explain what and why, not how (the code shows how).

Bad commit messages:

git commit -m "fixed stuff"
git commit -m "updates"
git commit -m "changes to landing page"

Good commit messages:

git commit -m "fix: resolve mobile navigation menu overflow on small screens"
git commit -m "feat: add password strength indicator to signup form"
git commit -m "docs: update API authentication examples in README"

Many projects use Conventional Commits:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation changes
• style: - Code style changes (formatting, semicolons, etc.)
• refactor: - Code refactoring
• test: - Adding or updating tests
• chore: - Maintenance tasks

Step 6: Push Your Branch

For Forked Repositories

Push to your fork:

git push origin feature/landing-page

For Direct Access (Private Repos)

Same command:

git push origin feature/landing-page

If this is your first push of this branch, Git might suggest setting the upstream:

git push --set-upstream origin feature/landing-page

Step 7: Create the Pull Request

Now comes the exciting part!

1. Go to GitHub and navigate to the original repository (not your fork)
2. You'll usually see a yellow banner saying "Compare & pull request"—click it!
3. Or click "Pull requests" tab → "New pull request" → choose your branch

Filling Out Your PR

Your PR has two main parts: title and description.

Title: Clear and concise, like a newspaper headline

Description: Tell the whole story. Here's a template:

## Summary

Fixes #156 - Adds a new landing page with responsive hero section and feature highlights.

## What Changed

- Created new `LandingPage.jsx` component
- Added responsive CSS Grid layout
- Implemented mobile-friendly navigation
- Added hero section with CTA button

## Why These Changes

The current homepage doesn't clearly communicate our product value to new visitors. This redesign:
- Improves first impression with clear value proposition
- Increases mobile usability (65% of our traffic)
- Follows our new brand guidelines

## Screenshots

### Desktop View
![Desktop landing page](url-to-screenshot.png)

### Mobile View
![Mobile landing page](url-to-screenshot-mobile.png)

## Testing

- [x] Tested on Chrome, Firefox, Safari
- [x] Tested on mobile devices (iOS and Android)
- [x] Verified accessibility with screen reader
- [x] All existing tests pass

## Checklist

- [x] Code follows project style guidelines
- [x] Added/updated tests
- [x] Updated documentation
- [x] No breaking changes
- [x] Tested locally

## Additional Notes

The hero image is placeholder—waiting on design team for final asset.

Step 8: The Review Process

Once your PR is open, maintainers will review it. Here's what to expect:

You Might Get Feedback

Don't panic! Code review is normal and healthy. Common feedback includes:

• "Can you add tests for this?"
• "This breaks our coding style, can you run the formatter?"
• "Great work! Just one small change needed..."

Responding to Feedback

Be professional and gracious:

Making Changes After Feedback

Just commit and push to the same branch:

# Make your changes
git add .
git commit -m "test: add unit tests for LandingPage component"
git push origin feature/landing-page

The PR automatically updates with your new commits!

Common Pitfalls and How to Avoid Them

❌ Working on main Instead of a Branch

Problem: You made changes directly on main and now can't create a clean PR.

Solution: Create a branch from your current state:

git checkout -b feature/my-changes
git push origin feature/my-changes

Then reset your main:

git checkout main
git reset --hard origin/main

❌ Your Branch is Behind main

Problem: The main branch got updates while you were working, and now there are conflicts.

Solution: Sync your branch:

# If you forked the repo
git checkout main
git pull upstream main
git checkout feature/landing-page
git merge main

# Or use rebase (cleaner history)
git checkout feature/landing-page
git rebase main

❌ Too Many Unrelated Changes in One PR

Problem: Your PR changes 10 different things, making it hard to review.

Solution: Keep PRs focused on one thing. If you have multiple improvements, create multiple PRs.

❌ Massive PRs with Thousands of Lines Changed

Problem: Your PR is 3,000 lines and reviewers don't know where to start.

Solution: Break it into smaller PRs. Big features can be built incrementally:

1. PR #1: Add basic structure (200 lines)
2. PR #2: Add core functionality (300 lines)
3. PR #3: Add styling and polish (250 lines)

Best Practices for Great PRs

✅ Do

• Read the CONTRIBUTING.md file first - Most projects have contribution guidelines
• Start small - Fix a typo, improve documentation, tackle a "good first issue"
• Ask questions - Comment on the issue before starting if you're unsure
• Test thoroughly - Don't let reviewers find basic bugs
• Be patient - Maintainers are often volunteers with day jobs
• Follow up - If you haven't heard back in a week, politely ping the PR
• Say thank you - Appreciate the reviewers' time

❌ Don't

• Submit untested code - Always test locally first
• Ignore CI failures - If automated tests fail, fix them
• Take feedback personally - Code review isn't about you, it's about the code
• Ghost your PR - If you can't finish it, say so
• Demand immediate review - Maintainers have their own schedules
• Rewrite entire projects - Start small, earn trust, then tackle bigger things

Your First PR Checklist

Before hitting that "Create Pull Request" button:

• [ ] Did you create a new branch (not working on main)?
• [ ] Does your code work locally?
• [ ] Did you test edge cases?
• [ ] Did you write/update tests?
• [ ] Did you update documentation if needed?
• [ ] Does your code follow the project's style?
• [ ] Is your PR description clear and complete?
• [ ] Did you link related issues?
• [ ] Are your commits well-organized with clear messages?
• [ ] Did you review your own changes on GitHub first?

After Your PR is Merged

Congratulations! 🎉 You're now an open source contributor!

Clean up your local branches:

git checkout main
git pull upstream main  # or just 'git pull' for private repos
git branch -d feature/landing-page  # delete local branch
git push origin --delete feature/landing-page  # delete remote branch

Update your fork's main branch (if you forked):

git checkout main
git pull upstream main
git push origin main

Now you're ready for your next contribution!

Quick Reference Commands

# Initial setup (forked repo)
git clone https://github.com/YOUR-USERNAME/project.git
cd project
git remote add upstream https://github.com/ORIGINAL-OWNER/project.git

# Create and switch to new branch
git checkout -b feature/your-feature-name

# Make changes, then commit
git add .
git commit -m "feat: add your feature description"

# Push to your fork/branch
git push origin feature/your-feature-name

# Keep your branch updated
git checkout main
git pull upstream main
git checkout feature/your-feature-name
git merge main

# After PR is merged
git checkout main
git pull upstream main
git branch -d feature/your-feature-name

Learning Resources

• GitHub's Pull Request Tutorial
• First Timers Only - Projects welcoming first-time contributors
• Good First Issue - Find beginner-friendly issues

Final Thoughts

Your first PR might feel intimidating, but remember: every expert was once a beginner. The open source community generally loves helping newcomers, and most maintainers are thrilled when someone takes the time to contribute.

Start small, be respectful, and don't be afraid to ask questions. The worst that can happen? Your PR doesn't get merged, and you learn something for next time.

Now stop reading and go make that first PR! The open source world is waiting for your contribution.