Add checklists to your peer review process through templates

Introduction

In my interactions with clients, I frequently dedicate time to mapping out their development processes. This is often necessary as these processes are usually not documented or mutually agreed upon, and teams tend to operate based on best endeavours. One very quick win is to create a pull request template based around an agreed set of steps that need to be completed before a pull request can be merged. This is a great way to standardise your peer review process and ensure that all PRs follow the same steps, and everyone is aligned on what is expected. It’s also really easy to achieve in both Azure DevOps and Github.

How to create a pull request template in Github

In Github the file needs to be called pull_request_template.md, and needs to be available in the default branch of the repository. The file needs to be stored in one of the following directories:

• .github
• docs
• the root folder of the repository

How to create a pull request template in Azure DevOps

In Azure DevOps, you can create a pull request template by adding a file called pull_request_template.md or pull_request_template.txt to the default branch of the repository. It needs to be stored in one of the following directories:

• .azuredevops
• .vsts
• docs
• the root folder of the repository

There are some similarities between the two systems, so in order to keep things portable (and to make my demo quicker to create), I will save the file at docs/pull_request_template.md.

Create your pull request template

Ideally, you should get together and have a chat about what you want to include in your pull request template. This should be a living document and can be updated as you learn more about what works and what doesn’t. Ultimately, you want your template to set out the pre-requisites to handing over the pull request for review. This will ensure that the developer has completed all necessary steps before the code is reviewed thereby reducing the amount of back and forth between the developer and the reviewer. Here is a simple template with a set of typical steps:

## Note to developer

Hey young padawan, before handing over this PR, please make sure you complete all the steps in the checklist below. This will help to ensure that your PR is in a good state before it is handed over for review.

## Checklist

- [ ] You have given this PR a meaningful name
- [ ] You have brought your code up-to-date with the `main` branch
- [ ] Your code builds clean without any errors or warnings
- [ ] You are using approved terminology
- [ ] You have added unit tests
- [ ] You have updated the documentation
- [ ] You have placed a summary of the changes in the PR description

## Change Summary

- 

This markdown syntax will render as a checklist in the pull request description in both Azure DevOps and Github. That’s really useful since it will allow the developer to tick off each step as they complete it.

Push your template to the main branch

Once you have created your template, you need to push it to the main branch of your repository. This will make the template available to any future pull requests. If you have a protected main branch, you will need to create a pull request to bring this change into the main branch…but that pull request won’t have the benefit of the template!

What happens when you create a new pull request

So now you have your template in place, what happens when you create a pull request? When a new pull request is created, the template will be automatically added to the description. Here is the template in action in Azure DevOps:

Here it is in Github:

From there, the developer can tick off each step as they complete it. This will ensure that the PR is in a good state before it is handed over for review.

What next?

This pattern sets up a default template for all pull requests in your repository. You can extend upon this in two ways…

Additional templates

This gives you the ability to include further templates that can be selected when the pull request is raised. Use cases for this might be where you only need a template for certain types of pull requests. In the repository, any markdown file that is stored in a subdirectory called pull_request_template will be available to select during the pull request creation process. If I wanted to create a template that had specific steps for changes to unit tests then I could save that file at the path docs/pull_request_template/changes_to_unit_tests.md and it would be available to select when creating a pull request:

Note, this feature only seems to be supported in Azure DevOps, I cannot find the equivalent in Github.

Branch specific templates

You can also set up pull request templates specific to a given branch. If you operate a branch strategy where there are more than one branch that you create pull requests from, you can create a template specific to that branch. This is achieved by naming the file the same as the top level of the branch in a subdirectory called pull_request_template/branch. For example, if you wanted a template specific to pull requests raised from the develop branch, you would save your template at docs/pull_request_template/branch/develop.md. This template would auto generate when a pull request is raised from the develop branch.

Note, this feature only seems to be supported in Azure DevOps, I cannot find the equivalent in Github. This could be set up by using query parameters, link in references.

Wrapping Up

Creating a pull request template is a great way to standardise your peer review process. It will help to ensure that all PRs follow the same steps, and everyone is aligned on what is expected. This is really easy to achieve in both Azure DevOps and Github.

References

• Improve Azure DevOps pull request descriptions using templates
• Creating a pull request template for your GitHub repository
• Using query parameters to create a pull request