How to write great pull requests

With the growth of the company, people and projects change. To continue the development of the culture that we want to have in 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.

Approach to writing pull requests

• Describe the purpose of this pull request. For example:
  

  This is a stub for ...

  It makes it easier to display ...

  This corrects the appeal to ...

• Consider providing brief information on why this work took place (with corresponding links); Do not assume that 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 other than those who accept the discussion, now or in the future.
• Be specific in what kind of feedback you want to receive, for example: a pair of non-petty eyes, a discussion of a technical approach, a criticism of design, a review of a 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 clear way to report the status.
• @ mention the people you want to connect to the conversation, specify why. (“/ Cc @jesseplusplus to explain this logic.”)
• @ mention the teams you want to engage in the discussion, specify why. (“/ Cc github / security, any concerns with this approach?”)

Leaving feedback

• Familiarize yourself with the problem context and the reasons why this pull request exists.
• If you strongly disagree, take a couple of minutes before responding. Think before you speak.
• Ask, not argue. (“What do you think about trying ...?”, Instead of “Don't do that ...”)
• Explain your reasons why you think the code should be changed. (Not according to the style guide ? Personal preference?)
• Offer ways to simplify or improve the code.
• Avoid using derogatory words such as “stupid” when referring to the work that someone has done.
• Be humble. (“I'm not sure, let's try ...”)
• Avoid using hyperbole. (“NEVER do ...”)
• Strive to develop professional skills, general knowledge and product quality, through group criticism.
• Do not forget about the negative shade 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 a neutral one?
• Use emoji to clarify the tone. Compare “ Looks good ”And“ Looks good. ”

Responding to feedback

• Consider starting with expressing gratitude. Especially if the feedback turned out to be ambiguous.
• Ask for clarification. (“I don't understand, could you clarify?”)
• Specify, explain the decisions that you made to come to a solution.
• Try to respond to every comment.
• Link to all relevant commits or pull requests. (“Excellent solution! Implemented in 1682851”)
• If there is a growing misunderstanding or discussion, ask yourself whether the text is the best way to continue communication. Talk (virtually) face to face, then jointly consider publishing the results to summarize the offline discussions (convenient for those who will try to understand, now or in the future).

These guidelines were partially inspired by the code review Thoughtbot Guide.
')
Our guidelines approach 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 pull requests Do not forget to use this guide when you make a pull-request;)