A few weeks ago, I wrote a blog post about the art and science of reviewing pull requests.
Since then, I’ve received a few Slack DMs about pull request descriptions.
Mainly folks want to know, “What should I include?”
This same question also comes up when I’m working with a new team.
It’s a good question. A solid pull request description can open doors to quicker and more productive pull request reviews.
But we want to be careful that we’re not writing unnecessary novels for our team to read.
Since I’m most often using Github as my source control host, I love to use their pull request template feature. This allows me to create a standardized “form” for the devs on the team to fill out anytime they open a pull request.
In that template, I have a few key pieces of information that I include. Here goes.
1. The ticket number
Regardless of what project management software you are using (Jira, Asana, Pivotal, Trello, etc), it’s nice to include a link to the original ticket for the reviewer.
Often our PM ticket has more context than we want to include in a typical pull request, for example: acceptance criteria; due date; linked tickets; related documentation; links to the reported issue; etc..
2. Description
This may feel redundant, but I make sure that I include a section specifically for the author to describe what the pull request does.
Now, I don’t want them to describe line by line what the diff is. Instead I ask them to outline what functionality this pull request adds or changes, why we made the change, and what broader goals it helps achieve.
Including a very high-level overview about the diff also helps contextualize the change and raise the reviewer’s awareness before diving into the code.
3. Changes
Depending on the team’s branching strategy, I may include a section for the author to enumerate the various changes that this pull request includes.
I usually break these into two sections, “Features/Major Changes” and “Bug Fixes/Minor Changes,” so it’s easy to call out housekeeping items that may have snuck into the pull request.
This can be helpful for teams that use feature branches, as multiple changes may make it into a single pull request. Since we should always try to leave code better than we found it, we often include little bug fixes, dependency upgrades, or other small changes in a pull request.
Explicitly listing them out makes it easier to identify the possible cause for regression, if one occurs.
I also like to include a section for “Documentation Changes” as a reminder to the team that they should be keeping docs updated as they change the code’s functionality.
4. How to test features (if applicable)
I love when pull request authors include instructions on how to conduct an end-to-end test of their feature. Unit tests are great but being able to test someone’s code the way a user or external service would is often a great way to catch bugs before they get merged and deployed.
In some cases, this may be high-level instructions on where to click in the UI. Or it might be complex step-by-step instructions on how to set up the local database to recreate a wild-edge case that occurred in production for a small subset of users. Or it might include a Postman request of how to invoke a new backend API endpoint that is only ever called from a webhook.
Given that there are so many ways to test software, these instructions can save reviewers valuable time.
5. Open questions
Sometimes we open a pull request before we have everything figured out. Or maybe in the course of working on the ticket, we found more questions that we didn’t know we had. I love to include a place to document these open questions.
6. Deployment instructions
Finally, I sometimes include a section for deployment instructions depending on how a team’s deployment process is organized.
Most often, I use this for documenting new environment variables that need to be added. But this can also be a place to document manual data migration tasks that need to be run or other preconditions for deployment.
This helps make sure no one merges the pull request accidentally before completing those items.
A pull request template example
Github’s pull request templates are markdown files, allowing you to use all the markdown features available.
Another example I might propose when I join a new team looks like the template below. Notice I make use of markdown comments so that the authors don’t have to delete unnecessary text. :)
# [Ticket number](a link to the ticket)
## Description
<!-- What does this pull request do? Why did we make these changes? Is there anything else to note? -->
## Changes
### Features / major changes
<!-- List your changes -->
<!--
### Bug fixes / minor changes
List your changes if there are minor changes
-->
<!--
### Documentation changes
List your changes if there are documentation changes
-->
<!--
## How to test
Instructions for how a reviewer should end-to-end test your code change
-->
<!--
## Open Questions
Questions that we haven't answered yet or that came up while you were working on implementation
-->
<!--
## Deployment instructions
Environment variables, data migration, etc.
-->
Your turn!
I’m sure other folks have their own approach to building out pull request descriptions. I’d love to hear what works for you.