How to write the perfect pull request

As a company grows, people and projects change. To continue to nurture the culture we want at GitHub, we’ve found it useful to remind ourselves what we aim for when we communicate. We recently introduced these guidelines to help us be our best selves when we collaborate on pull requests.

Approach to writing a Pull Request

• Include the purpose of this Pull Request. For example:
  This is a spike to explore…
This simplifies the display of…
This fixes handling of…
• Consider providing an overview of why the work is taking place (with any relevant links); don’t assume familiarity with the history.
• Remember that anyone in the company could be reading this Pull Request, so the content and tone may inform people other than those taking part, now or later.
• Be explicit about what feedback you want, if any: a quick pair of 👀 on the code, discussion on the technical approach, critique on design, a review of copy.
• Be explicit about when you want feedback, if the Pull Request is work in progress, say so. A prefix of “[WIP]” in the title is a simple, common pattern to indicate that state.
• @mention individuals that you specifically want to involve in the discussion, and mention why. (“/cc @jesseplusplus for clarification on this logic”)
• @mention teams that you want to involve in the discussion, and mention why. (“/cc @github/security, any concerns with this approach?”)

Offering feedback

• Familiarize yourself with the context of the issue, and reasons why this Pull Request exists.
• If you disagree strongly, consider giving it a few minutes before responding; think before you react.
• Ask, don’t tell. (“What do you think about trying…?” rather than “Don’t do…”)
• Explain your reasons why code should be changed. (Not in line with the style guide? A personal preference?)
• Offer ways to simplify or improve code.
• Avoid using derogatory terms, like “stupid”, when referring to the work someone has produced.
• Be humble. (“I’m not sure, let’s try…”)
• Avoid hyperbole. (“NEVER do…”)
• Aim to develop professional skills, group knowledge and product quality, through group critique.
• Be aware of negative bias with online communication. (If content is neutral, we assume the tone is negative.) Can you use positive language as opposed to neutral?
• Use emoji to clarify tone. Compare “✨ ✨ Looks good 👍 ✨ ✨” to “Looks good.”

Responding to feedback

• Consider leading with an expression of appreciation, especially when feedback has been mixed.
• Ask for clarification. (“I don’t understand, can you clarify?”)
• Offer clarification, explain the decisions you made to reach a solution in question.
• Try to respond to every comment.
• Link to any follow up commits or Pull Requests. (“Good call! Done in 1682851”)
• If there is growing confusion or debate, ask yourself if the written word is still the best form of communication. Talk (virtually) face-to-face, then mutually consider posting a follow-up to summarize any offline discussion (useful for others who be following along, now or later).

These guidelines were inspired partly by Thoughtbot’s code review guide.

Our guidelines suit the way we work, and the culture we want to nurture. We hope you find them useful too.

Happy communicating!

Written by

Keavy McMinn

@keavy