The Backend Playbook

Appearance

🚀 Pull Requests & Code Reviews ​

In this chapter, we'll be covering pull requests and code reviews. Don't worry if you've never made a pull request or left a code review before; this chapter will help you get started in no time. 😊

We'll be focusing on the GitHub way of working on this page. However, you're free to explore other methods on the internet, as long as you adhere to our etiquette.

🔎 What Are Pull Requests & Code Reviews? ​

Pull requests, or PRs for short, are one of the best ways to get other developers to review your code and are an essential part of our workflow. They allow others to check if your code is correct, clean, and adheres to the project's standards. With a PR a dev can easily see the changes you've made against the branch the PR is targeting.

After someone has opened a pull request, other developers can leave code reviews about the changes made. These reviews come in the form of comments and a final 'verdict' that the reviewer provides.

The possible 'verdicts' that reviewers can give are:

  • ✅ Approved: The reviewer believes your code is good enough to merge into the target branch.
  • ❌ Changes Requested: The reviewer has found issues such as breaking changes, missing functionality, or code quality concerns.

If you don't understand a review or disagree with a comment, it's important to engage in a constructive discussion with the reviewer. 💬

Why are PRs and code reviews essential for our workflow? To ensure that no significant mistakes reach the development or production branches of our projects, we never commit directly to these branches. This means that all code you want to merge into development, production, or other main branches of our flow must result from a merged pull request.

🌱 Creating a Branch ​

All pull requests should be created from a seperate branch then the main branch. We use the following naming conventions for branches:

  • Feature Branches: feature/your-feature-name
  • Bugfix Branches: bugfix/your-bugfix-name
  • Hotfix Branches: hotfix/your-hotfix-name

If you have a ticket number, you should include it in the branch name. For example, if you're working on ticket #proj-123, your branch name should be feature/proj-123-your-feature-name.

After you've created a branch and made your changes, you can create a pull request.

📝 Creating Pull Requests ​

There are many ways to create a pull request. Here are some helpful resources to get you started:

Each PR targets another branch, known as the base branch. This should always be the branch you originally branched off from when creating your feature branch. By selecting the correct base branch, only the changes you've actually made are shown.

⚠️ Don't worry if you've accidentally selected the wrong base branch; you can always change it as long as the PR hasn't been merged yet.

🏷️ PR Title ​

The title of the PR should be a single line summarizing what you aim to accomplish. Often, the title of the related ticket is used as the PR title because it already encapsulates your objectives well. However, you're not obligated to use the ticket title.

✍️ PR Description ​

Every PR should have a description that provides a brief overview of all the changes you've made.

If the PR is fixing a bug, explain the bug and how you fixed it. This information can be invaluable, especially if the problem occurs frequently and should be addressed at a higher level. Don't hesitate to add references to tickets or other resources in your PR; extra information can help reviewers understand your intentions.

Some projects have a PR template. If the project you're working on has one, you should try to follow it to the best of your ability.

📝 If a project lacks a PR template or if the existing template is missing certain elements you'd like to see, you can always open a PR to create or update the template!

👀 Leaving Code Reviews ​

As mentioned earlier, code reviews have two main components:

  1. Leaving comments about the code.
  2. Providing a final verdict based on the comments.

The first step, leaving comments about the code, is done while reviewing the changes in a PR. If you see something that isn't clean or is simply incorrect, you can note this in a comment on the PR. You can also leave comments if you're seeking more information—for example, if you don't understand why someone chose to implement something a certain way.

💡 More information about leaving comments can be found here.

The second step, providing a final verdict, is done after you've left your comments. Depending on the severity of the issues you've noted, you can either Approve or Request Changes. If you request changes, the PR author must re-request a review from you so you can verify that the suggested changes have been implemented.

📄 More information about submitting your review can be found here.

You can also leave a single comment, which is handy when you're browsing PRs and notice something without conducting a full review.

⚖️ The most important part of leaving code reviews is to be thorough and fair. Don't just hit 'Approve' and expect someone else to find any flaws. It's better to leave no review than to provide an incomplete one.

🔄 Applying Requested Changes ​

We've covered how to create a PR and leave reviews on someone else's PR. But what do you do if someone requests changes on your PR?

When someone leaves a review on your PR, it's your responsibility to go over the requested changes and apply them to your code.

Here are some tips to help you along the way:

  • 🤔 Ask for Clarification: If you're unsure about what's wrong or what you need to change, don't hesitate to ask the reviewer for clarification. You can do this in the PR itself or send them a message on Slack if it's urgent.
  • 🗣️ Discuss Disagreements: If you understand what the reviewer wants you to change but don't agree with it, you can discuss it with them. Everyone is equal in a PR.
  • 💾 Commit Regularly: Commit the changes as you go. Just like when you're coding normally, there's no reason to group all the changes you make into a single commit.

After you've committed and pushed code that addresses the requested changes, you can mark the comments as 'resolved'. It's best to do this after you've pushed the changes so the reviewer can see that the code they reviewed is outdated and has been updated.

Once you've resolved all comments from a reviewer, it's important to re-request their review. This gives them the opportunity to look over the new changes you've made and ensure everything is correct.

🤝 Pull Request Etiquette ​

  • 🌐 Language: The most important thing in a PR is clear communication. Whether you write in English or Dutch doesn't matter as long as your message is understood.
  • 🤖 Using GPT (or other AI tools): Just as the language you use doesn't matter, the use of AI tools is also acceptable—as long as the description and title are clear and accurate.
    • However, avoid sharing sensitive information with GPT or other AI tools.
  • 🏆 Do What Is Right, Not What Is Easy: Taking the easy way out won't improve your code or your skills. Whether you're reviewing code or applying changes, always strive to do the right thing and avoid shortcuts.
    • Exceptions to this rule are rare. Always discuss any short-term shortcuts with a tech architect or tech lead!
  • 👥 Don't Just Create PRs: The only way we can keep up with all the PRs being created is if everyone also reviews PRs regularly. Try to do a couple of PR reviews per day; they often only take a few minutes.
  • 🛑 Don't Add New Logic to Approved PRs: An approved PR isn't supposed to change. If you need to add new logic to an approved PR, you can either create a new PR or dismiss the reviews on the PR.