Good Manners of a Pull Request & Some Best Practices

Published in

Delivery Hero Tech Hub

7 min readNov 17, 2021

Hey everyone,

As software developers/engineers when we want to write on something we primarily focus on technical challenges since they are easy to describe and do not have many grey areas. For this post, I want to change this a little bit and focus on more human interaction side. I will try to talk about the etiquette & good manners of a pull request.

Creating, reviewing, and handling pull requests is a subjective topic, every development team should find their own best practices about it. So in this article, I’m gonna walk you through some of the ways we are using in Yemeksepeti to make our pull requests better.

Some of them can be considered global and some of them are not, some of them may apply to only crowded teams and some of them may not be helpful to you. While reading please consider how would these ways fit your team.

Single Responsibility Principle of a Pull Request

Applying the single responsibility principle to pull requests is always a good idea.

Try not to include some additional stuff into the PR. For example, do not fix any typos other than your current context or do not add a tiny bug fix to a feature. In this way, you can easily describe your aim and prevent confusion. You can also eliminate the possibility of one change waiting for the other.

Title and Description of a Pull Request & Pull Request Templates

Title and description is the first place where you can inform your teammates about the changes. PR titles can be traced via searching so adding some key information on the title would be useful.

Description of a PR should always be prepared with the same attention, whether the PR has a small or huge change. Reviewing the pull request requires changing the context for the reviewer. One minute ago you were focusing on apples and now you are looking at oranges. In order to ease this context change, the description of a PR is our first weapon. You can include anything in the description like Jira tasks, crash logs, design visuals, etc. Do not restrict your imagination for the description, every detail matters.

Always think that anybody could read your PR anytime. So do not assume this PR is only for the current situation and for the current reviewers. You are leaving some piece to your codebase history. Describe everything with these attitudes.

There are lots of teams in Yemeksepeti, in our team we are using Github. Github lets you create Pull Request Templates (even though it is still primitive 😄) which can help you with the PR descriptions. I suggest you take a look at this feature, it can be very helpful 🚀

By using pull request templates you can define guidelines for your team for creating descriptions for the pull request.

There is an example pull request description below which was created with our template. You can create your pull request template by looking at the official documentation. These templates are actually markdown documents. You can set it as default or you can create multiple templates and use it via query params while creating your PR.

Thanks Samed Biçer for doing the research and creating this template for the team 🚀

Possible ways to make your Pull Request more understandable

For a long time running, big codebases (like we have in Yemeksepeti 😄) you probably have a modular project structure, and lots of common codes are being used on the entire project. If you have changed some code pieces that affect the entire project it would be nice to talk about why you have made this decision and warn reviewers to be more careful. Crowded teams probably people have their domains and mostly they work on related parts. So maybe they haven’t gone through the parts you are changing on the PR. It is the author’s responsibility to notify reviewers and keep the project safe.
Commenting for the lines on your PR is another best practice to help your teammates. I like putting official documentation, Stackoverflow, and article links to the related lines which solve some strange bug or bring a brand new concept to the codebase.
Another good practice is to arrange a meeting (probably an online one thanks to remote working 👨🏻‍💻 ) after creating the PR to tell your teammates about the PR content. Be humble and do not fall for quotes like best codes speak for themselves 😄. For long PRs this can really be helpful for directing your teammates for possible code pieces that you want to be looked at. Also while your teammates review the PR you can apply some small suggested changes on the fly. I think this approach is a really good way for everyone to express their opinions and also show your trust in them doing the changes live. This practice reminds me of pair programming and while remotely working I deeply understand the value of pair programming 💪🏻.
It is the author’s duty to test the code before PR. Do not present not working code to your teammates. As I mentioned in the second topic, reviewing PRs requires context changing for the reviewers. Show some respect to them and give the best possible PR experience both with codes and the execution.
A small but important thing, if you’ve changed something important with the PR after some reviewers have accepted it please do not forget to warn already accepted teammates to review again.

Language and attitude tips

Both reviewers and the author should be polite in the comments. Naturally, we may state some disagreements in the PR and it can bring unintentional tension between the reviewers and the author. Being polite is the best way to prevent it. Do not hesitate to use emojis and reactions to lighten the mood 🙂.
Our pull requests’ quality can be different from time to time according to different things like the subject of the PR, our mood, time limitation, etc. so keep in mind that nothing is personal in the PRs. Do not take comments personally. The comments are not judging your personality or your abilities, they are just focusing on the current code.
Try not to use only a few words when leaving or answering comments. Try to use sentences as much as possible. Also when you disagree with something please come up with an alternative approach in order to avoid an unproductive loop.
When you’re a reviewer and your suggestion is too complex to tell by sentences, consider creating a pull request to an existing pull request. You should embrace it as a good habit. With this approach, you become in the same shoes as the author and you can provide better ways to tell about your solution.
Let's talk about Language literally 😄. In my opinion code reviews should be in English as the software literature is. Using the team’s native language can be helpful to ramp up understandability but does not work in multinational teams. (Even if they are closed, PRs can be reviewed in the future. So if you have non-native language speaking people in the future your older PRs will be useless for them). Plus if you are a non-native English speaker doing pull requests in English can help you to improve your level.

BONUS: Some technical approaches to improve pull requests

Even though I’ve told you at the start I will focus on more human interaction I couldn’t leave this part out 😄.

You should run your unit test before creating the PR. Even better the team should have a continuous integration step that runs unit tests when a PR is created. By doing this you can save every reviewers time who will try to run unit tests. Also when the build step is running the PR gets blocked from being merged faulty.
You should use lint tools (static code analysis) to keep your code in line with the team's preferred styles. A similar step that runs lint checks on the PR when it is created can be formed. This way you can fix style errors before your teammates point them out.

Since every team has its own ways of creating and reviewing their pull requests lots of advice, opinions can be found in other articles which I left some of them below. I briefly told about our team’s practices.

Also, there are lots of stuff about the technical side of the pull requests so please read about them in order to make the best pull requests for your team 🙂.

Thanks for reading.
Please feel free to comment and share it if you like it. Also if you want to talk about your best practices please leave a response, I would be appreciated to hear them.
See ya! 👋🏻