Pull Request descriptions are documentation too. In fact, they may be one of the more efficient types of documentation. Pull Requests are unique in that they maintain a record of how our code changes over time, combined with the ability to attach text in the form of a description to them as well. This ability to attach a large amount of text to an increment of code changes is not something that we see anywhere else in our ecosystems as developers. We can add comments to our code, but long in-depth explanations shouldn't belong in our code.
By building a culture of writing out detailed PR descriptions, we can enable Pull Requests to be yet another resource available for a developer. Ever see a line or block of code that is slightly confusing? You can navigate to that line in your GitHub repository and view the Git Blame for that particular line.
Notice that in addition to detailing which commit the change belonged to, it also links the Pull Request! If this Pull Request has a well-written description, then this might clear up confusion on this particular line of code.
Most people likely aren't used to using Pull Requests in this type of way, likely because if they tried to they would be met with a blank description 95% of the time. But, if you and your team get into the habit of writing descriptions, you'll be able to reap the benefits of a documented history of your codebase.
The Anatomy of a good PR Description
Hopefully by this point, I have convinced you that PR descriptions are important. And like with all documentation, the truth is that writing something is better than writing nothing at all. If you are in a time crunch and need to publish a PR as soon as possible, then even a few lines explaining the change are better than nothing. By the same token, our documentation gets better when we approach writing with a bit of strategy.
In GitHub, you can use Markdown in your PR Descriptions to help format your thoughts (yet another reason why You should learn Markdown). Let's take a look into how I like to format my Pull Request Descriptions.
Link to Task
If you're working in any team, chances are you do some type of task management, be it in Jira, Asana, Trello, etc. Therefore the work you are doing in any given PR has some logical counterpart on your Sprint Board. The very first thing you should type in your PR Description is the following:
[Link to task.](https://myteamsjiraurl.com/mystory)
This now creates a link between the task management system and the actual code itself. Whenever someone goes to review this PR, they can go view the relevant story to get an idea of what exactly this PR should be accomplishing.
Linking the story also gives additional context to those who might be viewing your PR from 6 months in the future. If they see a code change they are trying to find out more about, having the context behind the work itself is incredibly useful.
Background
After linking the Task URL, I oftentimes add a section that gives some detail into the reasoning behind my changes. Perhaps you had to choose between two solutions - this is a place to justify why you chose the solution that you did.
Another example is if you have some complex code logic. This section would be a great place to explain that logic - it helps both your PR Reviewers and anyone who comes back to this PR looking for additional information.
In some cases, writing a Background might be unnecessary. For example: if the change is a routine vulnerability remediation, then likely not much explanation will be needed. A link to the task from the previous section will be enough to explain the contents of the PR.
Determining when it is necessary to write a Background, and how to write said Background, is a super important skill that can take your PR descriptions to the next level.
Changes
A Changes section is necessary for a PR description. It also happens to be a fairly easy section to write - just make a bulleted list of all the changes you have made.
Go through your Pull Request and write one-liners for the high-level changes you have made. Here is an example:
- Added the business logic for onboarding a brand new user
- Refactored the existing user login code to share some components with the new onboarding logic
- Added some unit tests for the user onboarding scenarios
This Changes list can be super simple - it is meant to be a snapshot of the work you've done in this code increment. Again, this just increases the visibility and readability of your work.
Doing this also forces you to proofread your code as well. This is a valuable exercise to help you catch any minor typos or mistakes you have made before sending it off to your team. It also forces you to go over the code you wrote - oftentimes when I am writing my Changes list, I see a piece of code that I wrote and think of an even better way to rewrite it and optimize it.
Screenshots
Depending on the type of work you do, adding Screenshots might not be applicable. However, if you're doing any type of Frontend Web or Mobile app development - screenshots should be an absolute must.
Adding screenshots can show your reviewer what the change looks like in your app. This saves them from having to check out your branch and build the app themselves to view your changes.
You can also use these screenshots to show a Product Manager or Designer the work that you have done - I've found that they always greatly appreciate that.
Another option, though more time-consuming, is to record a video. While this may not be necessary for all changes you make, sometimes recording a video for big feature changes is helpful.
Use GitHub PR Templates
A large part of writing PR Descriptions can feel very Boilerplate-y. This is why learning to leverage PR Templates is super helpful. If you're using GitHub it is super easy (I am sure other Git repository hosts make it easy as well).
For GitHub, just follow the instructions here. Here is an example template that I use in all of my personal projects.
[Link to Task.](https://www.notion.so/XXX)
## Background
If applicable, provide some background about the choices you made in this PR.
## Changes
- ...
## Screenshots
If applicable, provide some screenshots below.
## Review Checklist
- [ ] Proof Read Code
- [ ] Write PR Description
- [ ] Request Review
This will render into the following when I open a PR:
Notice it contains the 4 pieces we've talked about here, in addition to a Review Checklist. I add this checklist to keep me honest and make sure that I proofread my code and write a description before I ask anyone for review. Feel free to edit this template to suit your needs.
Ultimately, writing PR Descriptions shouldn't feel like a drag. Make it a point to spend no more than 5 minutes writing your description before submitting it for review. If you can get an entire team to follow this methodology, you might be surprised to see the impacts it makes.
Top comments (0)