How to Open a Pull Request on GitHub

Pull requests are the heart of collaboration on GitHub. They let you propose changes, discuss them with your team, and merge them into the main codebase in a controlled, reviewable way. Here’s how to create one from start to finish.

Step 1: Create a Branch

Branching isolates your work from the main codebase so you can experiment without breaking anything. Always start from the latest version of the main branch:

# Start from the latest main
git checkout main
git pull origin main

# Create a feature branch
git checkout -b fix-login-bug

Use descriptive branch names like fix-login-bug, add-user-dashboard, or refactor-auth-service. This helps reviewers understand the purpose at a glance.

Step 2: Make Changes

Work on your changes incrementally. Commit often with clear messages so you can track progress and revert specific parts if needed:

# Work on your changes
git add .
git commit -m "Fix login bug when email contains special characters"

# Push to GitHub
git push -u origin fix-login-bug

The -u flag sets the upstream tracking, so subsequent pushes can use just git push.

Step 3: Open the Pull Request

1. Go to your repository on GitHub
2. Click “Pull Requests” → “New Pull Request”
3. Select your branch (fix-login-bug) against main
4. Fill in the PR template

GitHub will show you the diff automatically. Take a moment to review it yourself before submitting — you might catch issues early.

Writing a Good PR Description

A great PR description answers three questions: what, why, and how. Here’s a template:

## Description
Fixed a bug where users with special characters in their email
couldn't log in.

## Root Cause
The email validation regex didn't allow the '+' character.

## Changes
- Updated email regex in `validators.py`
- Added test cases for special characters

## Testing
- ✅ Unit tests pass
- ✅ Manual login tested with emails containing +, &, = 
- ✅ All existing tests pass

## Related Issues
Closes #142

Link related issues with keywords like Closes, Fixes, or Resolves so GitHub auto-closes them when the PR merges.

PR Best Practices

Keep PRs Small

• One PR per feature or fix — don’t bundle unrelated changes
• Fewer than 400 lines is a good target
• Split large changes into multiple PRs

Small PRs get reviewed faster, have fewer merge conflicts, and are easier to revert if something goes wrong. If you’re refactoring and adding a feature in the same area, do them in separate PRs.

Write Good Commit Messages

✅ feat: add user profile page
✅ fix: correct email validation regex
✅ refactor: extract auth logic into service
❌ update stuff
❌ fix
❌ changes

Consider using Conventional Commits (feat:, fix:, refactor:, chore:) — many tools can generate changelogs automatically from these prefixes.

Respond to Reviews

1. Fix the requested changes
2. Push a new commit
3. Reply to the comment: “Fixed in abc123”

Don’t resolve conversations yourself — let the reviewer mark them as resolved. This gives them a chance to verify the fix is correct.

Reviewing a PR

When reviewing someone else’s PR, be constructive and specific:

✅ "The logic looks correct. Consider extracting this into a helper."
✅ "Can we add a test for the edge case where `data` is None?"
✅ "This change would affect the caching layer. Have we tested for that?"

Focus on: correctness, security, performance, maintainability, test coverage.

Avoid nitpicking style issues unless your team has an automated formatter. If the PR is large, suggest splitting it rather than reviewing 50 files at once.

Merging Options

Squash and merge is popular on teams that value a clean main branch history. Rebase and merge is ideal when each commit in the feature branch is meaningful and you want to preserve individual changes.

PR Checklist Before Submitting

• Code compiles / tests pass
• No debug code, print statements, or TODO comments
• Meaningful variable/function names
• Error handling added where needed
• Documentation updated if API or behavior changed
• No secrets or credentials committed
• PR description explains what and why

Common PR Mistakes

❌ PR with 50 files changed (too large)
❌ No description ("Fixed bug" tells me nothing)
❌ Ignoring review comments
❌ Force pushing after review (overwrites reviewer progress)
❌ Merging without approval
❌ Resolving conversations without the reviewer agreeing

One of the most common pitfalls is force-pushing after a review cycle. It rewrites history and makes it impossible for reviewers to see what changed since their last review. Instead, add new commits on top. If you must rebase, do it before requesting review, not after.

Technical Debt and Follow-Up PRs

Not every issue needs to be fixed in the same PR. When you find technical debt or refactoring opportunities while working on a feature, note them and create a follow-up issue rather than expanding the scope of the current PR. This keeps reviews focused and prevents feature branches from growing unwieldy.

PR Etiquette

• Respond to reviews within 24 hours — even if it is just “I will look at this tomorrow”
• Thank reviewers for their time and suggestions
• Do not merge your own PR without at least one approval (exceptions for trivial changes)
• Keep PR descriptions up to date as the scope changes during review
• Add context in comments when you push changes — reviewers should know what to re-review

Good PR etiquette builds trust and speeds up the review process. Reviewers who feel their time is respected are more likely to give thorough, timely reviews.

CI/CD and Automated Checks

Modern PR workflows typically integrate automated checks:

• Continuous Integration — automated tests run on every push to the PR branch
• Linting and formatting — code style is enforced automatically
• Code coverage — coverage thresholds must be met before merging
• Security scanning — dependency vulnerabilities are flagged

Configure your CI pipeline to run these checks on every PR push. A red CI status should block merging until the issues are resolved. This reduces the burden on human reviewers and catches common issues automatically.

Advanced PR Workflows

Draft Pull Requests

GitHub supports draft PRs that signal work in progress. Open a draft when you want early feedback on approach without indicating the code is ready for final review. Convert it to a ready-for-review PR when you are done.

Cross-Repository PRs (Forks)

When contributing to open source projects you don’t have write access to, fork the repository first:

# Fork on GitHub, then clone your fork
git clone https://github.com/YOUR_USER/project.git
cd project
git remote add upstream https://github.com/ORIGINAL_OWNER/project.git

# Create a branch, make changes, push to your fork
git checkout -b my-feature
# ... make changes ...
git push origin my-feature

# Open a PR from your fork's branch to the original repo's main branch

Keeping your fork synchronized with upstream is important for long-running PRs. Fetch from upstream and rebase your feature branch regularly to avoid merge conflicts.

Related: Learn Git branching strategies and merge vs rebase.

FAQ

Q: Should I squash commits before merging? A: It depends on your team’s preference. Squashing produces a clean main branch history. Preserving individual commits gives more granular context for git bisect and blame.

Q: How do I request changes on a PR as a reviewer? A: Leave specific, actionable comments on the relevant lines. Use the “Request changes” review status for blocking issues, or “Comment” for suggestions.

Q: What if a PR has been open too long? A: Break it into smaller PRs. Open PRs that stay open for weeks usually contain too many changes and accumulate merge conflicts.

Q: Can I reopen a closed PR? A: Yes. Closed PRs can be reopened as long as the branch still exists. If the branch was deleted, you would need to push it again.

Q: What is the difference between a draft PR and a regular PR? A: Draft PRs cannot be merged and signal that work is in progress. They are useful for early feedback. Regular PRs are ready for final review and can be merged once approved.

Q: How do I handle merge conflicts in a PR? A: Resolve them locally by merging or rebasing the target branch into your feature branch, then push the resolved branch. GitHub will detect the changes and update the PR status.

Related Concepts and Further Reading

Understanding pull request requires familiarity with several interconnected ideas and principles that together form a complete picture. Exploring these related concepts deepens your knowledge and provides context that makes the core material more meaningful and applicable. Each concept builds on the others, creating a web of understanding that supports deeper learning and practical application. Taking time to explore how these elements connect reveals patterns that accelerate comprehension and retention of new information.

The relationship between pull request and adjacent fields is worth particular attention. Many of the most important insights emerge at the boundaries between disciplines, where ideas from different areas combine to create new approaches and solutions that neither field could produce alone. Exploring these connections pays dividends in both breadth and depth of understanding, revealing patterns and principles that might otherwise remain hidden from view. Cross-disciplinary knowledge is increasingly valued as problems become more complex and interconnected.

For those looking to go beyond introductory material, several excellent resources provide deeper treatment of specific aspects of pull request. Academic journals, industry publications, authoritative reference works, and online courses each offer different perspectives and levels of detail. The key is to match your reading to your current learning goals and build knowledge progressively, focusing on quality over quantity in your study materials. A well-chosen resource that matches your current level is worth more than dozens of resources that are too basic or too advanced.