
Photo by Tinhte (Social Network)
Before we jump into the topic of Pull Requests (PR) itself, I want to add some background & highlight why it’s important to have proper guidelines for PRs.
We will be covering the following:
0. Background
1. How should I “Pull Request”?
2. How do I share the template with my “team”?
3. General Pull Request Guidelines (by Nick)
a few months back I joined a team and was leading 5–6 developers, all of whom had worked on entirely different projects with diverse experiences in the past from Backend-to-Frontend-to-AI.
Everything was going smoothly, except for thePull Requests. Anything that you merge to your codebase normally goes through a review process, a standard way; be it a bugfix, feature, or enhancement.
It seemed like everyone was creating PRs in different formats with no standard criteria at all
For this very reason, I had to ping developers for every PR that was a little over 8 files, since the project was new we were pushing a lot of code, and it was becoming unmanageable for me to Sync, Review & Code (more on this later), as I would get confused what the PR was about at times
I want to know a few things before I can start reviewing the Pull Request itself
What should I expect?
What is gonna be the outcome?
What steps should I take to test?
Since everyone is using their format and no matter how much you try if it's not documented, you will have to walk everyone through the whole thing over multiple PRs.
I talked to my friend Ahmed Khan & asked him if they were practicing anything remotely related to the issue that I was facing. He said we are using a template, I asked him to share.
To my surprise, it was a really good starting point, it didn’t answer 3 questions completely but it had the base, & that’s all I needed
Well, technically it should have been called a Push Request but who cares, right? 🤷♂
https://gist.github.com/zainzafar90/ad6dacbb633fcc80a2ab0848c4aaa3f0
We have different formats for Backend, Frontend & Bugfixes. For example, for Bugfixes steps to reproduce on main a branch are kind of important, and for the Backend, we have API changes or endpoints section as well.And yes add/remove sections based on what you think works for your team
Emojis are a personal preference, unless you code in grayscale
It is an actual PR but the content is replaced with mock data (the project is in stealth)
I’ll share how you include a template in your project directory and use it for both Gitlab and GitHub
You will need to follow a few steps to enable templates for PRs in GitHub
Create a PR template in your repo
Navigate to your repository on GitHub.
Create a new file in the .github directory. If this directory doesn't exist, create it.Name the file pull_request_template.md.Add your PR template content to this file. Save and commit the file.
Next time you create a PR it should automatically load the template 🎉
You will need to follow a few steps to enable templates for PRs in Gitlab
Create .gitlab directory at the root of your project. If this directory doesn't exist, create it.Createmerge_request_templatesdirectory within the.gitlabdirectory
Paste your template within the merge_request_templates directory “bug\_fix\_template.md” or “feature\_request\_template.md”Now whenever you create a new PR Gitlab has a dropdown for the template in PR creation mode
Select whatever templates you want to use ✨
Since Nick Skelton has already discussed in detail in the article “How to Pull Request”, I will just be stating 3 bullets for authors and 3 for reviewers, in case you want to see how good of an article Nick has written, please do give Nick’s article a shot.
Perform self-review: Perform a thorough self-review of your draft PR, and see if you’ve missed anything
Remove noise: Remove non-essential changes like whitespace or formatting from PRs to focus on meaningful code alterations, respecting reviewers’ time
Acknowledge every comment: During PRs to show engagement and respect; use simple or emoji reactions to indicate you’ve seen the feedback.
Check out the code: This one’s my favorite. Maintain two clones of a project: one for regular work and one for reviewing PRs, allowing you to switch tasks without disruption and build the branch for review in parallel.
Validate locally: validate changes locally to ensure they compile and are practical, enhancing your understanding and providing valuable, actionable feedback directly in the comments.
Nitpicking is a good sign: If reviews focus mostly on style, it indicates your code is fundamentally sound. Respond to nitpicking by promoting automated style checks and seeking existing style guidelines to streamline future reviews.
Mastering the Craft of Pull Requests isn’t only about code — it's about consistency, clarity & courtesy.
PRs aim should be to make the lives of both authors and reviewers easier. Keep them small, and let emojis speak when words fail to make the case unless you are super grayscale!
Cheers!