Why you should put effort into your Pull Request description
Tags: git, github, programming
Published: 2022-08-22 07:38:00

Pull Requests are the primary way new code is proposed, reviewed and merged. We know that Pull Requests are important. 

But programmers put in varying levels of effort in writing Pull Request descriptions.

## The minimal effort PR

An example of a minimal effort PR could be:

```
# Description

Added column feature to table.

```

It doesn't give any context why the change was made, nor the rationale, nor give any hints about what behaviours has changed or even give a link to an issue tracker to allow viewers to find this information.


## Why this may be occurring

It can be easy for us programmers to focus on the code, and see Pull Requests as the annoying but necessary step to get the code up for review. 

We can make the mistake in thinking PRs are simply perfunctory thing and the content's doesn't matter.

We may think 
- "If they are curious they will ask questions"
- Or "they can search up the related ticket if they are curious".
- Or "What's the point, once it's merged it's **_history_** anyway".

But this kind of thinking is short-sighted.

## Why careless PR content is harmful

Yes, reviewers should ask questions if things don't make sense. But you are:

A. Making it harder on your reviewers than it needs to be; and
B. More importantly, you are removing the valuable context about why a piece of code was added and links to important information.

I'll dig in a bit deeper about (B). 

**Code rarely remains static.** It evolves and over time it morphs into something very different from when it was originally concepted and created. The same piece of code may be based on different knowledge at different points in time.

There will be situations in the future that you or others need to understand why a certain code change was made. You can use git blame or history to find the code changes. But without proper PR descriptions the context is lost to history.

This kind of thinking is short-sighted.

If you write proper descriptions however, this rich information and context can be used by future programmers to understand the rationale behind your code and make quicker and more quality code decisions.



## Tips

Some things that have worked for me are to:

- Add a **descriptive title** for the PR

```
feat [ENG-1234]: Add ability to add feedback column to PR table
```

- **Specify at a high level all the important changes** made in your description. You don't need to get into detail but at least list at a high level, enough to give context to the corresponding code.

```
This PR adds the following updates to PR Table:
1. Users can now add a column to add feedback.
2. Touch support.
3. Updates to unit tests to reflect new interactions.
4. Update third-party packages to add animation support.
```

- Where there is **something of note** about the code changes specify this in the PR.

```
Note. This PR results in visual regressions to support better touch targets. See the images below...
```

- Include the **rationale** behind the code. You don't need an essay but a short line behind why the feature was added.

```
To allow users to add a column to add feedback information. For more information about the rationale check out this `[slack link](url)`.
```

- Include a **link to the issue tracker ticket**. If you decide to not include a rationale this is doubly important.

```
[https://this-is-an-issue-tracker.com/eng-1234](https://this-is-an-issue-tracker.com/eng-1234)
```

- (For front-end) Where visual changes are made include an **image or video**. 

- Use a PR template to encourage inclusion of information like description, rationale and PR Checklist.