3 ways to make better pull request descriptions
Tags: git
Published: 2022-05-20 14:03:17

---
title: 3 ways to make better pull request descriptions
published: true
description: 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.
tags: git
cover_image: https://images.unsplash.com/photo-1564941266766-8f6b85087b2e?crop=entropy&cs=tinysrgb&fit=max&fm=jpg&ixid=MnwxMTc3M3wwfDF8c2VhcmNofDM2fHxwdWxsJTIwcmVxdWVzdHxlbnwwfHx8fDE2NTI5NjUwODc&ixlib=rb-1.2.1&q=80&w=2000
canonical_url: https://cctplus.dev/3-ways-to-make-better-pull-request-descriptions
---

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.

```other
## 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:

```other
## 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.

{% embed https://gist.github.com/maeganwilson/e302f732ab3ba0d5e6dd93c07642c4b0 %}

> ✉️ Get articles directly to your [email](https://cctplus.dev/#/portal).


## 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:

```other
## 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.


- [How to make a pull request template on GitHub](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository)
- [How to make a merge request template on GitLab](https://docs.gitlab.com/ee/user/project/description_templates.html#create-a-merge-request-template)
- [How to make a pull request template on BitBucket](https://bitbucket.org/blog/save-time-with-default-pull-request-descriptions)

---

If you have any comments about this post, then make sure to let me know on Twitter, [@maeganwilson_](https://twitter.com/maeganwilson_) and follow me there.

> ☕ Support my articles by [buying me a coffee](https://checkout.stripe.com/pay/plink_1Ji13BBhq0W6Mf4HCqPAYBNo#fidkdWxOYHwnPyd1blppbHNgWjVgf39QQGFGU2pPakhHTVFdQEs0R1F8VTU1Ym1ATmByUG0nKSd1aWxrbkB9dWp2YGFMYSc%2FJzQxbjFsdDJiXDZOQWFOUDBubicpJ3dgY2B3d2B3SndsYmxrJz8nbXFxdXY%2FKipmZnF1aXB2K2Fgcyo2KHJkfHYocWooaGRuYChnYHFxYHcodXBpaSh3YHRwYHZxKGFgdmZ3bHVxbGprdionKSd1d2BpamRhQ2prcSc%2FJ1ZqcHdmYCVWZGt2JVV3aid4JSUl)