The Craft of Pull Requests

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.

Photo by Iván Díaz on Unsplash

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)

So…

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 the Pull 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

As a Reviewer…

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?

But! How..?

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

1. How should I “Pull Request”?

Well, technically it should have been called a Push Request but who cares, right? 🤷‍♂

Time to share the format that we have been using. We have improved it over time after getting feedback from multiple fellow developers.

Our PR Template:

https://gist.github.com/zainzafar90/ad6dacbb633fcc80a2ab0848c4aaa3f0

1. 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.
2. And yes add/remove sections based on what you think works for your team
3. Emojis are a personal preference, unless you code in grayscale
4. It is an actual PR but the content is replaced with mock data (the project is in stealth)

2. How do I share the template with my “team”?

I’ll share how you include a template in your project directory and use it for both Gitlab and GitHub

Photo by Tinhte (Social Network)

GitHub:

You will need to follow a few steps to enable templates for PRs in GitHub

1. Create a PR template in your repo
2. Navigate to your repository on GitHub.
3. Create a new file in the .github directory. If this directory doesn't exist, create it.
4. Name the file pull_request_template.md.
5. Add your PR template content to this file. Save and commit the file.
6. Next time you create a PR it should automatically load the template 🎉

Gitlab:

You will need to follow a few steps to enable templates for PRs in Gitlab

1. Create .gitlab directory at the root of your project. If this directory doesn't exist, create it.
2. Create merge_request_templates directory within the .gitlab directory
3. Paste your template within the merge_request_templates directory “bug_fix_template.md” or “feature_request_template.md”
4. Now whenever you create a new PR Gitlab has a dropdown for the template in PR creation mode
5. Select whatever templates you want to use ✨

3. General Pull Request Guidelines

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.

Authors:

• 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.

Reviewers:

• 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.

In the end…

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!