Pull Request Template – Andy Croll
Have your duties ever included reviewing code commits before they are merged into a codebase? If so, you know that the description provided with the change set can make a huge difference in the ease or difficulty of evaluating the change. But if you’re anything like me, once it comes time to actually write such a change description yourself, you sometimes draw a blank. When you’ve been elbows-deep in code, it can be hard to gain the needed perspective to write a useful summary for other developers’ consumption.
What if, instead of confronting a blank slate, you had a little extra guidance in writing up your pull requests? In today’s episode, guest chef Andy Croll will demonstrate how using a pull request template can improve a team’s communication around code reviews. Enjoy!
Video transcript & code
I'm here to talk about Pull Request Templates
In many of the most successful teams I've worked with, one of the methods used to share knowledge and improve each other as developers was to review each other's code.
So, for this quick screencast I'm going to presume that you agree with me that code review is a net good for you and your team, or this video is gonna somewhat pass you by...
So, let's set the scene, what are Pull Requests?
If you’re submitting work for review, pull requests are a great way to group related changes and discuss approaches and improvements before merging.
The audience for a pull request can be your immediate co-workers, other interested parties or even your future self.
I like to think of things in terms of the questions other people might have about our work.
When using version control we definitely cover off the the who and when. A pull request as a whole often provides the 'what' which leaves us with 'how' and 'why' to cover in more depth.
It is helpful to provide a useful description and set the context for the changes you have made.
Which means that when you open a new pull request, the 'description' field is pre-filled with the contents of a file.
You create the pull request template markdown file in your repository and Github does the rest.
Let’s go through my version of this file.
- What does this PR do?
- Why are we doing this? Any context or related work?
- Where should a reviewer start?
- Manual testing steps?
- Database changes
- Deployment instructions
- New ENV variables
Let's go through these one by one...
A broad description of the work undertaken in this group of commits.
This isn't just a collection of your one-line commit messages, however self explanatory you might think they are!
This is the most important part of the Pull Request for me. It's the why.
We’re very good, as developers, about describing the ‘how’ of code. In fact the code is the “how”. But we’re no so great an providing the context.
It’s also a good place to provide links to issues, errors or perhaps other sources.
We need to answer the question... "What is driving the changes in this bunch of code?"
This is a good place to broadly describe the important parts of your changes. Major new additions, files with significant changes.
This is your chance to help your reviewer look at the important parts of your code first.
Simple instructions to allow a reviewer to replicate the functionality of the changes you've made.
It's good to include a screenshot of a new feature, potentially highlighting changes as a result of this code
It will also give historical context if you have to come back to this code at a later date.
I like to include these sections to highlight areas that might affect deployment of the feature.
Migrations or new ENV variables might make deployment trickier or potentially make rollback difficult.
There might also be important changes or tasks to run post-deployment.
So here's the file again in it's entirety. Quite straightforward really.
You could include a little more explanation under the titles to explain the sort of content you're hoping to see in each section.
Some teams like to include a self-checklist, including another list of good things to do before getting someone to review.
This can be particularly important on open source projects where you may have lots of new committers unfamiliar with your codebase and conventions.
But why? Seems like a 'lot of hassle' right?
Even in the immensely complex world of surgery, a simple ninety-second checklist has cut the rate of fatalities by more than a third.
It's no different for any repeatable activity, a checklist helps avoid mistakes.
Anything you do over and over works more efficiently if you have a process you follow every time. Having a template is a solid way to help you write useful pull request descriptions. It helps you pause and answer the questions posed by the default headings in the template.
It may well be that some pull requests don’t need all of the sections, but you can always just delete the irrelevant parts. Using this template will mean you’ve thought about the information in each section, even it was only to say “nah, don’t need it”.
Adding a pull request template is often one of my first additions when I join a project. It's a battle-tested way to improve written communication within your team and it'll also make make you think about structuring your code as well - knowing you'll have to describe your changes in a coherent way.
Also it's a way to look brilliant when you first join a team!
I've been Andy Croll, thanks for listening, hope to see you soon.