Open Source Guide
Tutorials

Your First Pull Request

Complete step-by-step guide to creating your first pull request

Your First Pull Request

This tutorial will walk you through creating your first pull request (PR) from start to finish. Don't worry - we'll explain everything!

Estimated Time

30-60 minutes for your first PR. It gets faster with practice!

What is a Pull Request?

A pull request is how you propose changes to a project. Think of it as saying:

"Hey, I made some improvements to your project. Would you like to include them?"

The project maintainers will review your changes, suggest improvements, and eventually merge them into the main project.

Prerequisites

Before starting, make sure you have:

  • ✅ A GitHub account
  • ✅ Git installed on your computer
  • ✅ A code editor (VS Code recommended)
  • ✅ An issue to work on

Important

Always claim an issue before starting work! Comment on the issue to let maintainers know you're working on it.

The Complete Workflow

Step 1: Find an Issue

Browse our issue catalog and find something that interests you.

For your first PR, choose:

  • 🟢 A beginner-friendly issue
  • 📚 A documentation issue (no coding required!)
  • ⏱️ Something that takes 1-2 hours

Good first issues:

  • Fix typos in documentation
  • Add installation instructions
  • Create a README section
  • Write a tutorial

Step 2: Fork the Repository

Forking creates your own copy of the project.

  1. Go to the repository on GitHub
  2. Click the Fork button in the top-right corner
  3. Wait for GitHub to create your fork
Original Repo: github.com/AryanVBW/LinuxDroid
Your Fork: github.com/YOUR-USERNAME/LinuxDroid

What Just Happened?

You now have your own copy of the project where you can make changes without affecting the original!

Step 3: Clone Your Fork

Download your fork to your computer.

# Replace YOUR-USERNAME with your GitHub username
git clone https://github.com/YOUR-USERNAME/LinuxDroid.git

# Navigate into the project
cd LinuxDroid

What this does:

  • Downloads all project files to your computer
  • Sets up Git tracking
  • Creates a local copy you can edit

Step 4: Create a Branch

Branches let you work on changes without affecting the main code.

# Create and switch to a new branch
git checkout -b fix-readme-typo

# Verify you're on the new branch
git branch

Branch naming tips:

  • Use descriptive names: add-installation-docs
  • Use hyphens, not spaces: fix-typo-in-readme
  • Keep it short but clear: update-contributing-guide

Why Branches?

Branches let you work on multiple features simultaneously without mixing them up. Each PR should come from its own branch.

Step 5: Make Your Changes

Now for the fun part - actually making changes!

  1. Open the project in your code editor

    code .  # Opens VS Code

  2. Make your changes

    • Fix the typo
    • Add documentation
    • Implement the feature
    • Whatever the issue requires!

  3. Test your changes

    • Does it work?
    • Did you break anything?
    • Does it look good?

Example: Fixing a README typo

Before:

# LinuxDroid

Tranform your Android device into a Linux powerhouse.

After:

# LinuxDroid

Transform your Android device into a Linux powerhouse.

Step 6: Check Your Changes

See what files you modified:

# See which files changed
git status

# See the actual changes
git diff

Output example:

modified:   README.md

Step 7: Stage Your Changes

Tell Git which changes to include:

# Stage specific files
git add README.md

# Or stage all changes
git add .

What's staging? Staging is like putting items in a shopping cart before checkout. You're selecting which changes to include in your commit.

Step 8: Commit Your Changes

Save your changes with a descriptive message:

git commit -m "Fix typo in README: 'Tranform' → 'Transform'"

Good commit messages:

  • ✅ "Fix typo in README: 'Tranform' → 'Transform'"
  • ✅ "Add installation instructions for Ubuntu"
  • ✅ "Update contributing guidelines with PR template"

Bad commit messages:

  • ❌ "Fixed stuff"
  • ❌ "Update"
  • ❌ "asdfasdf"

Commit Message Tips

  • Start with a verb: "Fix", "Add", "Update", "Remove"
  • Be specific about what changed
  • Keep it under 50 characters if possible
  • Use present tense: "Fix" not "Fixed"

Step 9: Push to GitHub

Upload your changes to your fork:

# Push your branch to GitHub
git push origin fix-readme-typo

What this does:

  • Uploads your commits to GitHub
  • Creates the branch on your fork
  • Makes your changes visible online

First time pushing? Git might ask you to set up authentication. Follow the prompts!

Step 10: Create the Pull Request

Now create the actual PR!

  1. Go to your fork on GitHub

    • You'll see a yellow banner: "Compare & pull request"
    • Click that button!

  2. Fill out the PR form

    Title: Clear and descriptive

    Fix typo in README

    Description: Explain your changes

    ## What Changed
Fixed a typo in the README: "Tranform" → "Transform"

## Why
Improves documentation clarity and professionalism.

## Testing
- [x] Checked spelling
- [x] Verified formatting
- [x] Previewed in GitHub

Closes #123

  3. Click "Create Pull Request"

Congratulations!

You just created your first pull request! 🎉

Step 11: Respond to Feedback

Maintainers will review your PR and may request changes.

Common feedback:

  • "Can you fix this typo?"
  • "Please add a test for this"
  • "Let's use a different approach"

How to respond:

  1. Make the requested changes in your local branch
  2. Commit the changes 
    git add .
git commit -m "Address review feedback: fix typo"
  3. Push again 
    git push origin fix-readme-typo

The PR automatically updates with your new commits!

Don't Take It Personally

Code review is about improving the code, not criticizing you. Maintainers want to help you succeed!

Step 12: Merge!

Once approved, a maintainer will merge your PR.

What happens:

  • Your changes become part of the main project
  • The issue gets closed
  • You're now a contributor! 🎉

After merging:

# Switch back to main branch
git checkout main

# Update your local copy
git pull upstream main

# Delete your feature branch (optional)
git branch -d fix-readme-typo

Common Issues & Solutions

"I made a mistake in my commit"

Fix the last commit:

# Make your changes
git add .
git commit --amend --no-edit
git push --force origin your-branch

"I'm working on the wrong branch"

Move changes to a new branch:

git stash
git checkout -b correct-branch
git stash pop

"My fork is out of date"

Sync with the original repo:

# Add the original repo as 'upstream'
git remote add upstream https://github.com/AryanVBW/LinuxDroid.git

# Fetch latest changes
git fetch upstream

# Merge them into your main branch
git checkout main
git merge upstream/main

# Push to your fork
git push origin main

"I have merge conflicts"

Resolve conflicts:

  1. Open the conflicting files
  2. Look for conflict markers: <<<<<<<, =======, >>>>>>>
  3. Choose which changes to keep
  4. Remove the conflict markers
  5. Commit the resolution
git add .
git commit -m "Resolve merge conflicts"
git push origin your-branch

Best Practices

Before Submitting

  • ✅ Test your changes thoroughly
  • ✅ Follow the project's code style
  • ✅ Update documentation if needed
  • ✅ Write clear commit messages
  • ✅ Check for typos and formatting

In Your PR Description

  • ✅ Explain what changed and why
  • ✅ Reference the issue number: "Closes #123"
  • ✅ Add screenshots for UI changes
  • ✅ List how you tested
  • ✅ Mention any breaking changes

During Review

  • ✅ Respond promptly to feedback
  • ✅ Ask questions if unclear
  • ✅ Be open to suggestions
  • ✅ Thank reviewers for their time
  • ✅ Learn from the feedback

Next Steps

You Did It!

You now know how to create a pull request! Ready for more?

Find More Issues

Browse 58 issues across 14 repositories

Advanced Git

Learn advanced Git techniques

Code Review Guide

Master the code review process

Join Community

Connect with other contributors

Quick Reference

# Complete workflow in one place
git clone https://github.com/YOUR-USERNAME/REPO.git
cd REPO
git checkout -b your-branch-name
# Make your changes
git add .
git commit -m "Your descriptive message"
git push origin your-branch-name
# Then create PR on GitHub

Questions? Check our FAQ or ask in the community discussions.

Create a Branch

Learn how to create a new branch for your changes

Fork a Repository

Learn how to fork a repository on GitHub

On this page

Your First Pull RequestWhat is a Pull Request?PrerequisitesThe Complete WorkflowStep 1: Find an IssueStep 2: Fork the RepositoryStep 3: Clone Your ForkStep 4: Create a BranchStep 5: Make Your ChangesStep 6: Check Your ChangesStep 7: Stage Your ChangesStep 8: Commit Your ChangesStep 9: Push to GitHubStep 10: Create the Pull RequestStep 11: Respond to FeedbackStep 12: Merge!Common Issues & Solutions"I made a mistake in my commit""I'm working on the wrong branch""My fork is out of date""I have merge conflicts"Best PracticesBefore SubmittingIn Your PR DescriptionDuring ReviewNext StepsQuick Reference

Your Progress

0/12
0%
Next up:
IntroductionClick to continue →