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.

Add reviewers

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. 🙂

Answer questions

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.