DEV Community

Raman Butta
Raman Butta

Posted on

Step-by-Step Guide to Submitting a Pull Request on GitHub

This guide will take you from complete beginner to confident contributor by walking you through the entire pull request (PR) process.

Prerequisites

  • A GitHub account
  • Git installed on your computer
  • Basic command line knowledge

Step 1: Fork the Repository

  1. Navigate to the repository you want to contribute to on GitHub
  2. Click the "Fork" button in the top-right corner
    • This creates your own copy of the repository under your GitHub account

Step 2: Clone Your Fork Locally

  1. Copy the URL of your forked repository (click the "Code" button)
  2. Open your terminal/command prompt and run: 
   git clone https://github.com/YOUR-USERNAME/REPOSITORY-NAME.git
   cd REPOSITORY-NAME
Enter fullscreen mode Exit fullscreen mode

Step 3: Set Up Upstream Remote

  1. Add the original repository as a remote called "upstream": 
   git remote add upstream https://github.com/ORIGINAL-OWNER/REPOSITORY-NAME.git
Enter fullscreen mode Exit fullscreen mode
  1. Verify the remotes: 
   git remote -v
Enter fullscreen mode Exit fullscreen mode

Should show both your fork (origin) and the original (upstream)

Step 4: Create a New Branch

Never work directly on the main branch. Create a new branch for your changes:

git checkout -b your-branch-name
Enter fullscreen mode Exit fullscreen mode

Good branch names describe the work: fix-typo-docs, add-feature-x, etc.

Step 5: Make Your Changes

  1. Make the necessary changes to the code/files
  2. Save your changes
  3. Stage the changes: 
   git add .
Enter fullscreen mode Exit fullscreen mode

Or add specific files:

   git add filename.ext
Enter fullscreen mode Exit fullscreen mode
  1. Commit your changes with a meaningful message: 
   git commit -m "Brief description of changes"
Enter fullscreen mode Exit fullscreen mode

Step 6: Push Changes to Your Fork

Push your branch to your GitHub fork:

git push origin your-branch-name
Enter fullscreen mode Exit fullscreen mode

Step 7: Create the Pull Request

  1. Go to your fork on GitHub
  2. You should see a banner suggesting to create a PR - click "Compare & pull request"
    • Or go to the "Pull requests" tab and click "New pull request"
  3. Select the correct branches:
    • Base repository: original repo's main (or default branch)
    • Head repository: your fork's your-branch-name
  4. Fill in the PR details:
    • Meaningful title
    • Detailed description of changes
    • Reference any related issues (using #issue-number)
  5. Click "Create pull request"

Creating a PR illustration

Step 8: Respond to Feedback

Project maintainers might request changes:

  1. Make additional commits if needed
  2. Push them to the same branch
  3. The PR will automatically update

Step 9: Sync with Upstream (if needed)

If the original repository changes while your PR is open:

git checkout main
git fetch upstream
git merge upstream/main
git checkout your-branch-name
git merge main
# Resolve any conflicts, then push
git push origin your-branch-name
Enter fullscreen mode Exit fullscreen mode

Step 10: After Merge

Once your PR is merged:

  1. Delete your branch (both locally and on GitHub)
  2. Sync your fork's main branch: 
   git checkout main
   git pull upstream main
   git push origin main
Enter fullscreen mode Exit fullscreen mode

Expert Tips

  1. Keep PRs small and focused - address one issue per PR
  2. Follow project conventions - coding style, commit messages, etc.
  3. Write good commit messages: 
   Summarize changes in 50 chars or less

   More detailed explanation if needed. Wrap at 72 chars.
   - Bullet points are okay
   - Explain why, not just what
Enter fullscreen mode Exit fullscreen mode
  1. Reference issues in your PR description (e.g., "Fixes #123")
  2. Use GitHub's features:
    • Markdown formatting
    • Code reviews
    • Suggested changes
  3. Consider signing commits for extra verification

Common Workflows

Forking Workflow (described above)

Best for open source contributions where you don't have write access

Branching Workflow

If you have write access to the repository, you can create branches directly in the main repo instead of forking

GitHub CLI Alternative

Advanced users can use GitHub CLI to create PRs from the command line:

gh pr create --title "Your PR title" --body "Description"
Enter fullscreen mode Exit fullscreen mode

Now you're ready to contribute to projects with confidence! Start with small contributions to build your reputation in open source communities.

Top comments (0)