Pull Requests (PRs) are a fundamental collaboration tool in modern software development. They provide a structured way to propose changes, review code, discuss improvements, and merge new features into your project. This guide explains what pull requests are, how to create them, best practices for managing them, and solutions to common issues.
🎥 Video: GitHub Pull Request in 100 Seconds (2 mins) - A clear introduction to the pull request workflow
A pull request is a method of submitting contributions to a project. It's called a "pull request" because you're asking the project maintainers to "pull" your changes into their repository. Pull requests are not a core Git feature but are implemented by hosting platforms like GitHub, GitLab, and Bitbucket.
Pull requests offer several important benefits:
Pull requests can serve different purposes:
There is a great tutorial on the readme of this repo on making your first contribution. It's a great way to learn how to create a PR.
Following these best practices will make the pull request process smoother and more effective:
🎥 Video: How to do coding peer reviews with Github (12 mins) - How to conduct effective code reviews
✅ "Add user authentication feature"
❌ "Add authentication, profile page, and settings"Title: Add password reset functionality
Description:
- Adds an API endpoint for requesting password resets
- Creates email templates for reset instructions
- Implements a secure token-based reset mechanism
- Includes unit and integration tests
Fixes #234💡 Tip: If you're using GitHub Projects, you can add
fixes #<issue-number>to the PR description to automatically close the issue when the PR is merged. There are numerous other integrations with GitHub that can automate things in this way.
Before:
[Screenshot of old UI]
After:
[Screenshot of new UI]
This redesign improves mobile usability by 35% in our user testing.Ensure CI checks pass: Fix any failing tests or linting issues before requesting review
Respond promptly to feedback: Address review comments in a timely manner
Keep the PR updated: Regularly merge or rebase from the target branch to avoid conflicts
# Keep your PR up to date with main
$ git checkout main
$ git pull
$ git checkout feature/my-feature
$ git rebase main
$ git push --force-with-leaseBe timely: Review PRs promptly to avoid blocking team members
Be thorough: Check for bugs, edge cases, and adherence to coding standards
Focus on important issues: Distinguish between critical problems and minor stylistic preferences
Be constructive: Phrase feedback as suggestions rather than commands
✅ "We could improve performance by caching this result"
❌ "This is inefficient and poorly implemented"Ask questions: If something isn't clear, ask for clarification rather than assuming
Provide examples: When suggesting changes, provide code examples when possible
Recognize good work: Point out well-implemented parts, not just issues
Using PR templates can help standardize the information included in pull requests. Create a file named PULL_REQUEST_TEMPLATE.md in your repository's .github folder, and it will automatically appear in the PR description for any PRs you create.
## Description
[Describe the changes you've made]
## Type of change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update
## How Has This Been Tested?
[Describe the testing process]
## Checklist:
- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my own code
- [ ] I have commented my code in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature worksEven with the best practices, you may encounter issues with pull requests. Here are some common problems and their solutions:
Merge conflicts occur when changes in your branch conflict with changes in the target branch.
Symptoms:
Fix:
# Get the latest from the target branch
$ git checkout main
$ git pull
# Switch back to your branch
$ git checkout feature/my-feature
# Rebase on main
$ git rebase main
# Resolve conflicts in your editor, then
$ git add .
$ git rebase --continue
# Push the changes (force required after rebase)
$ git push --force-with-lease
⚠️ Warning: Always use
--force-with-leaseinstead of--forceto avoid accidentally overwriting others' work.
If your PR has too many small, messy commits, reviewers might ask you to clean up the history.
Fix:
Start an interactive rebase session to squash or reword commits.
# Interactive rebase to clean up commits
$ git checkout feature/my-feature
$ git rebase -i HEAD~5 # Replace 5 with the number of commits to include
# In the editor, mark commits to squash (s) or reword (r)
# Example in the editor:
# pick abc1234 Add login feature
# s def5678 Fix typo
# s ghi9012 Another small fix
# r jkl3456 Fix validation logic
# After saving, you'll be prompted to edit commit messages
# After completing the rebase:
$ git push --force-with-leaseSometimes you might accidentally base your PR on the wrong branch.
Symptoms:
Fix:
# If you need to change the base branch of your PR
# Method 1: On GitHub, edit the PR and change the base branch
# Method 2: Git rebase approach
$ git checkout feature/my-feature
$ git rebase --onto correct-base-branch original-base-branch
$ git push --force-with-leaseIt's important to be careful about accidentally committing sensitive data like API keys or passwords. If you do, you should immediately tell your teammates and work together with them to remove it.
⚠️ Warning: This doesn't remove data from the PR history on GitHub. Contact repository administrators to remove sensitive data from GitHub history.
Initial Steps:
# To remove sensitive data
$ git checkout feature/my-feature
$ git filter-branch --force --index-filter \
"git rm --cached --ignore-unmatch path/to/sensitive/file" \
HEAD
# Or for a specific commit:
$ git rebase -i HEAD~3 # Go back to before the problematic commit
# Mark the commit as 'edit' in the rebase list
# Make your changes, removing sensitive data
$ git add .
$ git commit --amend
$ git rebase --continue
$ git push --force-with-leaseContinuous Integration (CI) checks may fail on your PR.
Symptoms:
Fix:
# Fix CI failures
$ git checkout feature/my-feature
# Make necessary changes based on CI feedback
$ git add .
$ git commit -m "Fix failing tests"
$ git push origin feature/my-featureWhen reviewers leave comments on your PR, you should address each one:
# Make changes to address comments
$ git add changed-files
$ git commit -m "Address review feedback: improve error handling"
$ git push origin feature/my-featureOn GitHub, you can:
You can request specific team members to review your PR:
Sometimes the best approach emerges through collaboration:
💡 Tip: If a discussion gets complex, consider hopping on a quick call or chat to resolve issues more efficiently, then document the outcome in the PR.
