Communication, Practice Empathy

Adding more Empathy to Pull Requests

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.

Empathy

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?

My thoughts

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.

Thanks for reading! 🙂 If you enjoyed it, share it with a friend!

For more thoughts and examples on empathy in pull requests, check out this video where I dig deeper into the suggestions from this article.

  • Pingback: Rituals of Shaming in the Software Industry - Coding with Empathy()

  • Very good post Pavneet. I agree with what you are writing here.

    Thinking about these things can really help ground developers and help the process along alot!

    We actually usually do code review in the team every morning – so we have the developer showing the Pull Request to everyone – allowing him to explain things before we start and during the Code Review.

    The biggest problem with this approach is that if for some reason we cannot review the change right away, the developer might forget exactly what happened during development, why he did this and that, etc.

    • That’s an interesting approach. Great way to share knowledge and for everyone on the team to see which changes are going into the code-base.

      I had this discussion with the team in regards to taking the time to write down valuable insights as part of submitting a story to PR / CodeReview. That if you aren’t available a reviewer can start off with so much more context.