How to write great pull requests

Original author: Keavy McMinn
  • Transfer
With company growth, people and projects change. To continue the development of the culture that we want to have on GitHub, we found it useful to remind ourselves of the goals that we pursue in communications. We recently introduced these guidelines to help ourselves be better when we interact through pull requests.

Pull request writing approach

  • Describe the purpose of this pull request. For instance:
    This is a stub for ...
    This simplifies the display ...
    This corrects the call to ...
  • Think about providing a brief summary of why this work took place to be (with related links); don't assume everyone is familiar with the story.
  • Remember that everyone in the company can read this pull request, so the content and tone can inform people different from those who are taking the discussion, now or in the future.
  • Be specific in what kind of feedback you want to receive, for example: a pair of unencumbered eyes, a discussion of the technical approach, criticism of the design, review of the copy.
  • Be specific when you want feedback. If the pull request is in operation, then report it. The prefix “[WIP]” in the header is a simple and understandable way to report status.
  • @ mention the people you want to connect to the conversation, indicate why. (“/ Cc @jesseplusplus to explain this logic”)
  • @ mention the teams you want to engage in the discussion, indicate why. (“/ Cc github / security, any concerns with this approach?”)

Leaving feedback

  • Check out the context of the problem and the reasons why this pull request exists.
  • If you strongly disagree, distract for a couple of minutes before answering. Think before you speak.
  • Ask, not affirm. (“What do you think of trying ...?” Instead of “Don't do this ...”)
  • Explain your reasons why you think the code should be changed. (Not according to style guide ? Personal preference?)
  • Suggest ways to simplify or improve your code.
  • Avoid using derogatory words such as “stupid” when referring to work that someone has done.
  • Be humble. (“I'm not sure, let's try ...”)
  • Avoid using hyperbole. (“NEVER do it ...”)
  • Strive to develop professional skills, general knowledge and product quality through group criticism.
  • Do not forget about the negative connotation in online communication. (If the content is neutral, then we assume that the tone is set to negative). Can you use a more positive language instead of neutral?
  • Use emoji to clarify the tone. Compare “ imageimageIt looks good imageimageimage” and “It looks good.”

Responding to feedback

  • Consider starting with an expression of gratitude. Especially if the feedback is mixed.
  • Ask for clarification. (“I don’t understand, could you clarify?”)
  • Clarify, explain the decisions that you made to come to a solution to the issue.
  • Try to answer every comment.
  • Link to all relevant commits or pull requests. (“Great solution! Implemented in 1682851”)
  • If there is growing misunderstanding or discussion, ask yourself if the text is the best way to continue communication. Talk (virtually) face-to-face, then think together about publishing the results to summarize offline discussions (convenient for those who will try to understand now or in the future).

These guidelines were partly inspired by the Thoughtbot code review guide.

Our guidelines are relevant to the way we work and the culture we want to develop. We hope you find them useful too.

Have a nice chat!

All bug fixes and translation improvements can be sent via imagepull requests. Do not forget to use this guide when making a pull request;)

Also popular now: