How to create the perfect pull request

With the growth of the company, people and projects are changing. Not so long ago an interesting article appeared in the GitHub blog, in which the author tells how to do it, and how best not to do Pull Requests. Translation, traditionally, hidden under the cut.

The right approach to writing Pull Request

• Clearly define the purpose of this pull request. For example:

   …  … 

• It will be good if you include a brief description of why this work was done at all (including relevant links). Do not expect that the requester reading the developer will be familiar with the whole story.
• Keep in mind that this request may potentially be read by any employee of the company. Perhaps in a year.
• Explicitly write what kind of reaction you expect in response to this request. Do you want from reading something besides merge? Just look at the code, evaluate the technical implementation, criticism of the design, review of the text, and so on.
• Explicitly indicate when you expect an answer. If the request is in progress, it is common practice to add the “[WIP]” prefix (work in progress) to its description. This will allow readers to ship you early comments, while realizing that they are not looking at the finished work.
• @ Mention those whom you would like to see in the discussion of the request. And mention why, for this there is a special syntax:

   /cc @jesseplusplus for clarification on this logic 

• @ You can mention not only developers, but also teams. The same applies to the reasons as why you want to discuss with them:

   /cc @github/security, any concerns with this approach? 

')

Reaction to someone else's pull request

• Try to explore the context in which this pull request occurred: related tasks, discussions, background. If all this is, of course.
• If the pull request causes you to have an instinctive negative reaction - take a timeout of a few minutes and check everything carefully again. Perhaps the author is not an idiot you just had a communication error. This happens surprisingly often.
• Ask, but do not offer. A simple and effective psychological trick to facilitate communication. The phrase “What do you think about using ...?” Provokes much less conflict than “do not kill yourself ”.
• Try to explain why you need to change the code (contrary to the style of coding ? Personal preference?)
• Suggest ways to simplify and improve the code. This is perceived much better than just criticizing “everything is bad.”
• Speaking of criticism. Try to avoid ratings like "stupid" in relation to someone else's work. It helps to establish communication very well.
• You have to be modest. For business it is necessary - “not sure, but let's try ...” helps to find a common language much better than “I have been doing this for 20 years. Do not ask why. ”
• Avoid hyperbole (“NEVER do ...”). All perceive them quite differently.
• Set your goal to develop professional skills, company knowledge and increase product quality. Sounds jaded? Yes, but usually they aim to entertain their self-esteem by criticizing.
• Consider “negative bias” of online communications (for neutral content, we always assume a negative tone). In order not to put emoticons in the text, you can use the "positive" language.
• If a “positive” language is difficult to use (for many years journalists have been learning this for a reason), then emoji comes to the rescue, oddly enough. Compare: ": sparkles:: sparkles: Looks good: +1:: sparkles:: sparkles:" and “Looks good”.

Someone else's reaction to your pull request

• Whenever possible, begin to reply with thanks, especially if the response to your request is inconsistent.
• If something is not clear, feel free to ask clarifying questions (“I don’t understand, can you clarify?”). This is much more effective than trying to "invent" by yourself what the other developer meant.
• Try to provide all the clarifying information and talk about the reasons for certain decisions in the code.
• Try to respond to every comment.
• Link commits and other pull requests (“Good call! Done in 1682851”)
• If the discussion begins to escalate into debate, stop and ask yourself if it makes sense to continue the dialogue in writing. Practice shows that in most cases it is much more convenient to discuss everything on Skype or another voice chat, and then only add a brief squeeze and the result of the discussion as text.

I was inspired to write the post here is this guide . I described the techniques that we use in our work and the culture that we are trying to adhere to. We hope that you will find something useful among them.

Successful communications!