Writing good Pull Request descriptions

As developers, we like to get work done quickly. There is a feeling that if we finish fixing an issue or completing an issue as quickly as we can, then is obvious to the other team members, who may not be developers, that we are good at what we do because we get things done quickly.
This is dangerous, it can lead to bad practices slipping into your teams’ processes, where developers are trying to cut corners and get that Pull Request (where a developer asks the rest of the team to ‘pull’ their code into the main codebase of an app) ready as soon as possible.
One area where this cutting corners can happen is in PR (Pull Request) description messages, where the developer explains what this PR is about. If this is not completed then all the other member of the team who is reviewing the PR (where a second developer looks at the code changes made, and checks for any problems or can suggest ways that something might be done in a more efficient way), this second developer will just be shown a list of files, with the code changes highlighted.
From that, they need to work out what this PR is trying to either fix or add to the app’s codebase. Usually, without this context, the second developer will look at the changes, and think ‘well the syntax of the code looks fine, there are no obvious problems with how it’s written, I’ll Approve it’. Then this new PR is added to your app’s codebase, it all works and everything is fine.
But a few weeks later your users are complaining that the app has a strange issue when they use it. So you ask your developers to look into the cause of the problem. It could be due to something that has gone in the latest version of the app. So as any good developer should, they look through all the PR’s that went into that last release of the app.
This is where having a good description of what was done for a PR is so important. Yes, you can find a branch number that matches the list of the branches of code that went into a release, but if there is no description or no context of what work was completed as part of the PR, then it all becomes a guessing game.

So what goes into a good description?

There are a couple of things I think should go in a PR description:
1. Ticket number and title
2. A brief explanation of work completed
3. Bullet list of changes made

Adding a Ticket Number and Title

The title of a PR can have a lot of different variations, I’ve seen some places where the title is used to show a log of the changes made. From the PR’s in a release a log showing all the titles was used to show a report of what went into a release. This is helpful, but it meant that all the PR titles needed to be in a certain format and this format wasn’t particularly reading for humans.
Having the title of the ticket and the title number in the description as the first line makes it possible for a developer to see what was the corresponding ticket (if we’re using Jira) and what the name of the ticket was. Then the developer can search for that ticket and get an overview of what the PR was trying to do.

A brief explanation of work carried out

Next, I would add a brief, a few paragraphs, not an essay, an explanation of what work was carried out, what was added or fixed and how this was done. So someone could read this and get a sense of what was completed in the PR.
This doesn’t have to be too much, just enough so anyone knows what work was carried out.
A description is not only useful to other developers who may have to work on an old PR but also the original developer, to remind them of what they did for the PR.

Bullet list of changes

This is where you just list the changes you made. Maybe list each amended or new file and list what changes were made. Something like:

1. Add new sort function to account service
2. Removed commented out code from the interface
3. Add unit test for main login service

Along with the title, brief description and bullet list of changes it is clear what went into a PR. Making it easier for developers in a team to be able to see what went into a PR.

Some developers in your team might say that this is a was of time, and if you need an explanation of what some code does then it’s not well-written code, but I think that’s laziness on the developers’ side. No one’s code is that easy to read, especially after a few months. Having your developers follow the good practice of adding a description to any PR they make will no doubt help the team. The more the team know what’s been added to the code base the quicker a fix for an issue with an app can be fixed, the faster the fixed app can be released to your users.

If your team aren’t using descriptions in their Pull Request’s then maybe its time to ask them why, and if they say it takes to long then make sure this effort is included in the estimates they give. It’s work the time in the long run.