Pull Request Guidelines
Pull requests are a good way to learn from your colleagues and teach them new things. They are also helpful for documenting why and how the system has changed over time.
Here are some guidelines, which should help you write more effective ones:
💌 When creating pull requests
Give a meaningful description
The code diff of a pull request is what has changed, but not why and how. Give a short explanation of what the goal of your change is.
For bigger changes or changes that touch critical parts of the code base, you should give a longer description of how a certain goal has been achieved.
In the best case you elaborate the advantages and disadvantages of different solutions you’ve considered.
Make visual changes visible
Small CSS changes don’t need an elaborate description.
For visual changes add a screenshot or a gif to the description. This is the easiest way to provide context for your changes.
On Mac we recommend using the native Screenshot tool and Gifox for recording the screen as a gif.
Review your own code first
Before requesting other people to review your code, try doing it yourself first. This often helps to see your code from a different perspective, which can result in finding typos, hard to understand parts or architectural design problems.
Every code going to production should be seen by at least two pairs of eyes. Always assign Max to pull requests and add other developers from your team or a third party agency we are working with.
Don’t hesitate to assign designers as well. If they don’t have a GitHub account yet, help them create one. 🙂
Always answer questions before taking action.Other people might not have as much knowledge about the code as you do, so they need to ask questions to give better feedback.
🕵️♀️ When reviewing code
Use passive voice
Give feedback in a way, so that you are talking about what the code does, not what the author does. For example:
👎 “You are iterating over this list here, but forgot to filter out inactive items.”
👍 “This [code] iterates over a list without filtering out inactive items.”
Don’t ask rhetorical questions
Only ask questions if you need more context to give meaningful feedback.
Rhetorical questions are better formulated as actionable feedback.
Explain why things should change
Remember to give a reason why things should change. Maybe you forgot something and your suggestion is not valid given more information.
Additionally pull requests are also a very good tool to teach your peers. Explain them why things might be better done in a certain way, so that they can apply it the next time.
👯 Find the best solution together
The goal of a pull request is not to merge code.
The goal is to get a better understanding of the problem together by providing a possible solution. This means after discussing the solution you might end up discarding the code and solve the problem differently. This shouldn’t be the norm, but don’t hesitate to start from scratch.