Setting up the Quintessential PR Templates

Before we go deep into details, let's consider the below scenario:

You are standing in an open field where you have started to build your dream house.

The house is a carefully constructed masterpiece, with solid foundations and a beautiful facade matched by an elegant interior.

Around the back of the house, you see a long line of people, all of them holding little white envelopes. They seem very eager to help with the house.

There are two mailboxes here.

The first mailbox is simply labeled issues (“I am not going to talk about it, I have a lot of my own.”).

The second is mysteriously labeled — Pull Requests.
And yes now we will talk about the second mailbox.

I hope you all have got the gist of the matter now. So there are good samaritans out there to help you with your project and they are full of ideas!!
They are energetic, resourceful and all super imaginative. ;)

So what do you do?

You say that’s simple, I already have a mailbox out there and people can submit their requests which I can go through it later. Easy-peasy!!

And what do you see after some time?

You find yourself overloaded with requests and losing context and grip over your codebase….oopsy I meant house!!

The beautiful foundation laid by you is now an interesting foundation with a lot of things brewing in.

For example, you recently approved a pull-request to build a bathtub, you looked at the design and said yeah that would be cool!!
The next thing you see is, it was built in front of your house and with no provision of water pipeline!!

The person imagined you having a bath in the midst of nature and you got sold to the idea and overlooked the details and the architect himself was so engrossed in getting things into action that he overlooked a few basic details!!

Long story short, you need a system to get things in order. A system that can be subtle and effective at the same time and you come up with certain guidelines, do’s and don’t, must’s and should’s and that's how templating was born.

Let's begin,

As developers, our responsibility is not only to fix issues or implement new features but to clearly communicate the development work to reviewers.

A developer can convey proposed code changes and their purposes either through detailed documentation(PRD, TRD) or other means of communication

Providing descriptions for pull requests is highly recommended for a better code review process. Descriptions clearly answer:

• What can reviewers expect while reviewing the submitted code?
• What standards has the developer considered before submitting their code for review?
• Has the developer thought about the path ahead

And due to the overwhelming nature of our work, some of these things might become difficult to track, and hence the PR templates.

When you initiate a new pull request for an implemented feature or a bug fix in your project repository, you can allow the description field to pre-populate with a checklist of items relevant to your team, like the checklist provided in the previous section. This process of exhibiting the pre-filled description field in the pull request form is a Pull Request Template.

How do I set it up?

Create a file called pull_request_template.md in your project's root directory. You can add checklists as per the nature of your repo.

Below is the sample template I use in my projects:

<!--- Provide a general summary of your changes in the Title above -->

## Description
<!--- Describe your changes in detail -->

## Motivation and Context
<!--- Why is this change required? What problem does it solve? Link to PRD, TRD?-->
<!--- If it fixes an open issue, please link to the issue here. Add the Linear issue number. -->


## Types of changes
<!--- What types of changes does your code introduce? Put an `x` in all the boxes that apply: -->
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to change)

## Backward compatibility
<!--- Does it affects exiting contracts? Have you checked your dependent systems?  -->
- [ ] API
- [ ] DB

## How Has This Been Tested?
<!--- Please describe in detail how you tested your changes. -->
<!--- Include details of your testing environment, and the tests you ran to -->
<!--- see how your change affects other areas of the code, etc. -->

## Migration and deployment details (if appropriate)
<!-- add your deployment strategy, for eg: do you need to run some migrations, backfilling -->


## Screenshots (if appropriate):


## Checklist:
<!--- Go over all the following points, and put an `x` in all the boxes that apply. -->
<!--- If you're unsure about any of these, don't hesitate to ask. We're here to help! -->
- [ ] My code follows the code style of this project.
  - [ ] I have checked the **Code Quality Reports**.
- [ ] My change requires a change to the documentation.
  - [ ] I have updated the documentation accordingly.
- [ ] I have added tests to cover my changes.
- [ ] All new and existing tests passed.
- [ ] I have updated my dependent systems.
- [ ] My change may put additional load on the system
  - [ ] I have load tested the system

And Boom!! Now whenever someone creates a new PR, the description template is pre-filled and the relevant details can be added.

Github PR Template in action

So what have we realized?

Setting up a PR template is a very small task but does go a long way in maintaining the quality of your codebase. At times it can eliminate the need for RCA, as some things can be ensured by following the checklist and over-sights can be eliminated.