3 ways to make better pull request descriptions

#git

A pull request, aka merge request, is crucial in the git workflow when working on a team. If your project has CI/CD setup, it is usually the piece that needs to be merged to trigger code to production. This post outlines three ways to make your pull request descriptions better.

1. What and Why

Make sure you are clear about what your code does and why it’s essential. Explain what it does and include whatever is necessary to show what it does. GitHub allows images and gifs in the pull request description, so if those would help illustrate you’re point, then do it. Including a why lets the code reviewer know the purpose of the pull request.

How does What and Why differentiate

The what and why of a pull request might seem similar, but they are quite different. The what of the pull request explains what the code does, and the why defines the pull request's impact.

Example

I want to submit a PR that updates ESLint.

## What

This PR adds a new ESLint rule to adjust the import order

## Why

It makes the code easier to read and easier to follow by organizing imports in a predictable way. It also groups imports by siblings and parents.

In the example above, the what says what the code does and the why explains how the pull request is necessary.

2. How to determine if this PR is good to merge

Mention how the reviewer is supposed to test the pull request works in the description. Explicitly stating how the code reviewer is supposed to evaluate the code will make it easier for them.

Example

Building on the above example:

## What

This PR adds a new ESLint rule to adjust the import order

## Why

It makes the code easier to read and easier to follow by organizing imports in a predictable way. It also groups imports by siblings and parents.

## How to test

1. Open a JavaScript file
2. Change the import order
3. Save file and see how it changed

The above example is a great start, but a way to take it up a level would be to actually give before code and after code in the description like this.

✉️ Get articles directly to your email.

3. Create a template

If you have a structure to your pull request, you should create a template. A template gives pull requests structure since it guides the author on what they should include. It also ensures that all the necessary pieces to the pull request are there.

A sample template might look like this:

## What

Describe what this PR does

## Why

Describe the impact that this PR makes

## How to test

Describe how to test that this PR does what it says it does

## Checklist

- [ ] Ran all tests locally
- [ ] There are no credentials stored in the code
- [ ] Has this been signed off by PM or designers or any other stakeholders?

Here are links to making a pull or merge request template on GitHub, GitLab, and BitBucket. I found these by googling “How to make pull request template on {platform}” so if your platform isn’t here, then you can probably find it using the exact search.

If you have any comments about this post, then make sure to let me know on Twitter, @maeganwilson_ and follow me there.