When I first started out as a developer, I learned that no one knows everything right away. Some skills, like submitting and reviewing pull requests (PRs) are rarely taught in programming courses and can only come through hands-on practice. Since learning is an ongoing journey, I love sharing what I’ve picked up along the way. In this post, I want to build on one of my earlier articles How to Run and Submit Code, or Advice to Myself a Year Ago.and help you get more comfortable with PRs.
I would like to take a closer look at Pull Requests:
what they are
why they matter
how to both submit and review them
etiquette
what to avoid
If you're new to contributing to projects, this guide will help you understand the workflow and feel more confident in your role as a contributor or reviewer.
🧐 Understanding Pull Requests
What is a Pull Request (PR)?
A Pull Request (PR) is a way to propose changes to a project. It tells your team that you’ve made changes to a separate branch and you’re ready for them to review and possibly merge those changes into the main branch (often called main or master in older projects).
Think of a PR as raising your hand to say: “Hey, I’ve made some updates! Can you check if everything looks good before we include (or merge) it in the main codebase?”
What is a Feature Branch?
A feature branch is like a sandbox for your work. It’s a separate version of the code where you can develop new features or fix bugs without affecting the main codebase. Once your work is complete and reviewed, you can merge your feature branch back into the main branch. This way, the main codebase stays stable and clean.
📨 How to Submit a Pull Request
Before submitting a PR, make sure you ask about PR guidelines in your team. The rule of a thumb:
Create a new branch and a descriptive branch name, such as
feature/user-authenticationYou can do it in the terminal using this command:
git fetch origin git checkout -b <new-feature-branch-name>
Write clear commit messages that explain the changes you made
Review and test your own changes to catch issues early
Rebase regularly on the main branch to prevent merge conflicts. These situations happen when your changes overlap with changes others have made
When you're ready to submit:
Push your feature branch to the remote repository (e.g., GitHub)
Open a new Pull Request on the platform you’re using (e.g., GitHub)
Fill out the PR template with a clear description, including:
What the PR does
Why it’s needed
What ticket it closes in the task manager
Capture the state before and after the changes
Steps to test it
🎩 Pull Request Etiquette
As a Submitter
Create descriptive branch names (e.g.,
feature/fix-login-bug).Write clear commit messages that summarize your changes.
Keep commits logical and focused on one specific task.
Rebase on the main branch before submitting to avoid conflicts.
Test your changes thoroughly before opening the PR.
📝 Pull Request Template
Here’s a simple template to use when submitting a PR:
# Pull Request Title
## Purpose
Briefly explain the purpose of this PR and the problem it solves.
## Closes
What issue or ticket it solves
## Changes Made
- List of changes made
- Any important decisions or dependencies
## Before & After
### Before
- What was the behavior before these changes?
- Screenshots of the before state in case of UI changes
### After
- What’s the behavior after these changes?
- Screenshots of the after state in case of UI changes
## Testing Steps
1. Step-by-step instructions for testing
2. Include test data if needed
3. Describe expected results
🔍 How to Review a Pull Request
Getting Started
If you’re assigned to review a PR, here’s how to start:
Open the repository on GitHub and read the PR description carefully. Look for details like:
The purpose of the changes
Any decisions made during development
Known limitations or considerations
Instructions for testing in local environment (aka on your computer)
Set up the code locally for testing:
Clone the repo if you haven’t already
Switch to the feature branch using these commands in the terminal:
git fetch origin git checkout <feature-branch-name>Open the project in your code editor, like VS Code
👀 During the Review
Examine the code changes:
In GitHub, go to the Pull Requests tab and click on Files Changed
Look for issues like:
Code style: Does the code follow project guidelines
Bugs: Could there be any issues with the code?
Security concerns: Are there any potential security risks?
Performance: Could the changes slow things down?
Test the changes locally:
Follow the testing steps provided in the PR description.
Install dependencies if this is required based on the PR description (e.g., using
npm installoryarn)Run automated tests if this is mentioned in the PR
Check edge cases (aka unusual or extreme scenarios) to make sure the code handles them well
Verify that the feature works as described in the PR (purpose and After in the PR description)
Provide feedback:
Comment on specific lines of code by clicking the
+sign next to themAdd general feedback in the Conversation tab of the repo on GitHub
Keep your comments friendly and constructive
Approve (If there are no merge conflicts):
There is a big green action button at the bottom of the page. If you are happy with the changes and there are no merge conflicts, you should be able to select Approve on it
If you are not happy with the changes - select “Request a change” and submit this selection
If you see a message about a merge conflict, you need to notify the pull request creator by leaving a comment about it
🎩 Pull Request Etiquette
As a Reviewer:
Be timely with your reviews so your teammates aren’t blocked. Usually a branch requires two reviewers to approve its PR for the branch to be merged and closed
Stay constructive and respectful. The goal is to help, not criticize
Be clear about what needs to be changed and why
Suggest improvements, and provide links to relevant documentation if needed
Differentiate between required changes and optional suggestions
If something isn’t clear, ask questions instead of assuming
Approve the PR once you’re satisfied with the changes
🙅♂️ Common Pitfalls to Avoid both in Submitting and Reviewing
Avoid:
Submitting large, unfocused PRs. Keep them small and digestable
Ignoring code style guidelines in your team
Not testing changes locally before submission
Writing no or vague PR descriptions
Being unresponsive to feedback
Making major changes without a request for it and discussion
Merging without approvals