Pull Requests: How to Get and Give Good Feedback
We follow a typical GitHub flow: develop in feature branches off master, open pull requests for review and discussion, then merge and deploy. My favorite part of this process is the pull request. I think that the way a team interacts with pull requests says a lot about the healthiness of its communication. Here’s what we’ve learned at Kickstarter about getting and giving good feedback.
Giving Good Feedback
Before you begin, consider that someone has potentially spent a lot of time on this code, and you are about to begin a semi-public conversation where you search for problems and suggest ways that the code could be better. You want to be polite, respectful, courteous, and constructive.
All of these things can be accomplished by being curious.
Start by searching for places that don’t make sense or that act in surprising ways. When you find one, ask a question! Maybe you found a bug, or a way to simplify. In this case, asking allows the submitter to participate in the discovery. On the other hand, maybe the feature has a good reason that you overlooked. In this case, asking gives the submitter an opportunity to explain, and gives you a chance to learn something new.
Suppose that your question was a misunderstanding, and it’s all settled now. Or suppose that you figured out the answer on your own. That’s not the end! You can still contribute: think about how the code was different than you expected, and suggest how it might be clarified for the next person.
The best part of this approach is that anyone can do it at any skill level. You’ll either end up contributing constructively or learning something new. Maybe both! There’s no bad outcome.
Getting Good Feedback
When preparing a pull request, remember that this is not an adversarial situation, it’s not a step that you outgrow, and it’s not a hurdle on the way to production. Imagine instead that you are a writer submitting a first draft to a panel of editors. No matter your skill level, you will benefit from fresh eyes.
Before submitting, try to remove distractions. Skim through what you’re about to submit. Does it have any obvious stylistic issues, or code left over from previous iterations? Did you make stylistic updates to unrelated code that could be merged and deployed separately? Now’s your chance to clean up your branch and let people focus on the good stuff!
Then write up a good description. Your goal in the description is to describe why you’ve done this work and how you’ve approached the solution. But that’s not all: this is an opportunity to talk about where you’d like extra eyes and @-mention who you’d like to take a look.
Once you’ve submitted and you’re waiting for feedback, take yet another look through your code. In some cases you might seed the conversation by commenting on spots where you’d like to draw attention. But don’t explain too much just yet! You don’t want to spoil those valuable first impressions.
By now coworkers are engaging with your pull request and beginning to ask questions. Be welcoming! Every question provides an opportunity to learn where your code caused someone to stumble. Remember that if you have to clarify in the pull request, you should additionally consider clarifying the code as well. Your goal is to commit code that not only accomplishes what it intends, but can be understood and maintained by your entire team.
When pull requests have healthy communication, they’re moments that engineers can relish and look forward to. They provide an opportunity for participants to learn from each other and collaborate on making something of a higher quality than any single person might have achieved on their own. If you feel that pull requests have been missing something in your organization, try out some of these ideas!
Written by Lance Ivy.