When I'm working with a new team, a question that comes up often is "What info should I include in my PR description?" A good PR description can open doors to quicker and more productive PR 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 PR. And in that template, I have a few key pieces of information that I include.

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 would want to include in the PR: acceptance criteria, due date, linked tickets, related documentation, links to the reported issue, etc.

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. I don't want them to describe line by line what the diff is, but instead what functionality this PR adds or changes, why we made the change, and what broader goals does it achieve.

A high-level overview for the diff a reviewer is about to look at helps contextualize the change and raise their awareness before starting their code review.

Changes

Depending on the team's branching strategy, I may include a section for the author to enumerate the various changes that this PR includes. I usually break these into "Features/Major Changes" and "Bug Fixes/Minor Changes" so that it's easy to call out housekeeping items that may have snuck into the PR.

This can be helpful on teams that heavily use feature branches as multiple changes may make it into a single PR. Since we should always be trying to leave code better than we found it, we often make little bug fixes, dependency upgrades, or other small changes in a PR. Listing them explicitly 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 functionality.

How to test

I love when PR 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 our software, these instructions can save reviewers valuable time.

Open questions

Sometimes we open a PR 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.

Deployment instructions

Finally, I sometimes include a section for deployment instructions depending on how a team has their deployment process organized. Most often I use this for documenting new environment variables that need to get 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 can make sure no one merges the PR accidentally before completing those items.

Template example

Github's PR templates are markdown files so you can use all the markdown features available to you. An example I might propose when I join a new team looks like this. 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.
-->