Using tools like GitHub or BitBucket allow developers to able to submit their changes through pull requests. One of the challenges with pull requests is that they often contain very little information, apart from the change itself and perhaps the issue or case in question. Bad pull requests make the lives of reviewers a lot harder, and mean they need to spend a lot of time understanding the context. Instead of focusing on the change itself.
So, how can you improve your pull requests? Duretti and Mark from Slack Engineering suggest that we add more empathy to pull requests to make them easier for the authors and reviewers alike.
Duretti and Mark use Dr Brené Browns definition of empathy:
Four Components of Empathy, by Dr. Brené Brown
- to be able to see the world as others see it
- to be nonjudgmental
- to understand another person’s feelings
- to communicate your understanding of that person’s feelings back to them
Empathy is a skill that we have to learn and practice — mastery comes from practice.
Improving Pull Requests
It’s so important to realise that in an asynchronous flow like pull requests, the reviewer(s) often lack a lot of the context that the author has while attempting to fix an issue. They go on to say:
Basically, your reviewer is totally missing context, and it is your pull request’s job to give them that context. You have a few options:
- Give it a good title, so people know what they’re getting it into before they start.
- Use the description to tell your reviewer how you ended up with this solution. What did you try that didn’t work? Why is this the right solution?
- Be sure to link to any secondary material that can add more context — a link to the bug tracker or a Slack archive link can really help when describing the issue.
- Ask for specific feedback — if you are worried that the call to the `fooBarFrobber` could be avoided, let them know that so they can focus their effort.
- Finally, you should explain what’s going on for your reviewer. What did you fix? Did you have any trouble fixing the bug? What are some other ways you could’ve fixed this, and why did you decide to fix it this way?
The premise of this article is that there is a completely asynchronous workflow between the author and review of the code. This probably means they don’t speak together on a regular basis. This is quite common in distributed teams or teams with very clearly defined roles.
Writing a pull request with the reviewers context in mind is a wonderful way to ease the effort needed to actually get started with reviewing the code at hand. These steps to improving pull requests make a lot of sense, but should be used on a case by case basis.