4 Tactical PR Best Practices

tl;dr for faster reviews and a stronger team, do these four things:

1. annotate your own PRs, add a 🥩 or 🔑 to the lines that are the crucial changes
2. prefix review comments with nitpick, FYI, question, or please change to remove ambiguity
3. ensure your PRs link back to the product story
4. how does this PR make you feel in gif format?

Introduction

There are lots of great articles about PR best practices, but I find most of them are somewhat vague and don’t actually improve my practices. For example, I know my PRs should be small, but knowing that doesn’t help me make them smaller. In this post I want to share a few tactical, practical suggestions for improving your PR review process. They are easy to do and you can start today! I have used these on my teams to dramatically speed up review time and team cohesion. Let’s dive in.

The List

1. The author must annotate their own pull request to add context and to call out which are lines are key changes.

A PR description provides a good summary of the changes, but we can do much better. By adding focused notes on specific lines, a PR author gives the reviewers crucial context into what they’re looking at, and can help them allocate their attention accordingly.

Any moderately sized pull request will have enough line changes such that it’s not immediately obvious which changes are cosmetic (eg a function rename), which are structural (eg a refactor), and which are logical (eg fixing a bug or adding new functionality). Knowing in advance what kind of change you're looking at helps you activate the correct brain circuitry for the task and avoids wasted time trying to grok the relative importance of a particular diff. It’s also a great place to add commentary or explanations of changes so the reviewer doesn’t have to guess at the author’s intentions.

Key changes in a PR are the core functionality requested in the story. These deserve the most scrutiny and should be called out with a distinctive emoji. I’ve used 🥩 to denote “the meat of the change” but you can also use 🔑 if you’re an animal-sensitive team. The point is that whatever emoji you choose serves to call your team’s attention to the crucial part of the PR.

An additional benefit of adopting this annotation technique is to alleviate the pressure of Unavoidably Large PRs. A helpful emoji lets you skip the parts that are file renames and go straight to the important changes.

2. Reviewers must prefix their comments with either nitpick, suggestion, FYI, or please change to denote what type of comment this is.

Communication is tough. Communication over the internet is a miracle. Anyone who has sent and received messages over the internet knows that tone, intent, and subtlety are lost over the wire. That’s why it’s critical to provide as much written information and context in your messages as possible. Although it may seem tedious and redundant, prefixing your review comments with a categorizing word can work wonders towards shared understanding. Here are the ones I use:

• nitpick - a better name for a function, a grammatical error, etc. Expresses the reviewer’s opinion/aesthetic but does not meaningfully alter functionality, which is working correctly. (If functionality is incorrect the comment would fall under please change.) The author may ignore these comments, and reviewers should keep them to a minimum.
• FYI - background information on the change for the edification of the author or other reviewers on the team. Examples include business context, technology details (using this syntax prompts the compiler to do X), or alternate solutions to a problem. The author may choose to make changes based off this additional information at their discretion.
• question - a question for the author, which could be about their approach or their reasoning or their tactics.
• please change - a change which must be made in order for approval to be given. Many teams use Github’s built in Changes Requested functionality, but this doesn’t specify which changes need to be made. I recommend also adding annotated comments to the lines that must be changed.

For example:

• question - what happens if this API call fails?
• please change - this API call needs error handling
• FYI - this API is scheduled to change in 6 months
• nitpick - a map is better than a list for passing options to this API call

You might think “but isn’t it obvious what I mean by this comment?” And the answer is: surely not. It might be obvious to you, the writer, but what matters is whether it’s obvious to the reader. Good practices exist to eliminate avoidable classes of errors; adopting an explicit categorization system for your team’s comments thus removes a huge source of potential misunderstanding.

3. Your PR should link back to the story.

This one is so easy. And being able to quickly refer back to requirements is such a helpful timesaver. All mainstream story trackers have Github integrations that will post a backlink to the story to the PR as soon as it’s opened. Make sure yours is set up, and that you follow the correct branch name protocols so that the integration works correctly. Here are instructions for JIRA, Shortcut, Linear, Monday, Pivotal Tracker, and Trello.

4. How does this PR make you feel in gif format?

This last technique is a team building superpower. At the end of the PR description, or in the first comment, the author embeds a gif that expresses how they feel about the PR. The gif could be funny, it could be sad, it could be inspirational, it could be exasperating. Whatever it is, it’s expressive, and it serves two crucial purposes:

1. It gives the rest of the team context into the author’s state of mind and thus social cues as to how to leave feedback. If the author is clearly burned out on a bear of a PR, a relevant gif signals to the reviewers that sarcastic commentary would be particularly unwelcome. Or if the author is jubilant their team can share in a joyful moment. In an era where many teams are remote and we have minimal insight into our colleagues’ internal state, these gifs can generate the emotional connection that glues high-performing teams together. They also give managers crucial insight into how an individual is doing and can prevent burnout.
2. It creates an emotional outlet for the author which an outlet for the emotional experience of the work. This kind of release does wonders for an individual's mental health that must be seen to be believed. It's a kind of mini-therapy that processes challenging experiences faster and reinforces beneficial states of mind.

Your team will likely balk at the idea, thinking it is silly and a waste of time. Within a week they will take to it. At Mrgr we believe that engineers are humans and humans have feelings, whatever the stoic stereotypes would have you believe. And the more humans can express their feelings, the better they feel. Adding a gif to one’s PR improves overall wellbeing and resilience, and can even serve as a bullet to bite during a trying coding session, eg “when i get through this I’m going to find the best PR to perfectly sum up how crappy this code is.” I cannot recommend this practice enough.

In Conclusion

We all want to deliver better software faster, but the question is- how? These four actionable techniques will improve review times and build a more coherent, resilient team of individuals. And the best part is you can put them into practice right away.

‍