How to make a good pull request

A pull request or merge request — is an event that takes place in software development when a contributor/developer is ready to begin the process of adding new code changes to the main project repository.

The main reason to use pull requests is to facilitate a beneficial code review process. Knowing this, our job as contributors/developers is to make it easy for our reviewers to review our code, following the guidelines below.

Disclaimer: This tutorial is not about how to create a pull request, is about how to make a good one.

Conventional naming

Is very important to follow a consistent structure for your branches and commits depending on what you will be adding.

• For your commits, I recommend that you follow the conventional commits guidelines.
• For your branch I recommend you depending on the change the following structure:

type/ticket_number + phrase of three words describing the change:
feature/23-add-new-button

Finally, for your pull request name, you must consider what type of change you are adding depending on your change. Do not add a feature that fixes a bug and also refactor things. Keep your pull request small.

Good Description

The description is the cover letter of your work, and you should include everything you think is necessary to provide the necessary context for your reviewers.

What should have a good description?

• Explanations of what you did: very small resume of what you did.
• Links: ticket, design, or live demo: to give more context.
• Screenshots or code snippets: to clarify or prove what you did.
• Checklist: Things like “Reviewed by designers” or similar should suffice.

Keep it simple keep it small

This is very important and has many benefits — creating small pull requests will help your colleagues to review them faster and more efficiently, this means:

• Less likely to introduce bugs.
• Easier to merge.
• Easier to design well.
• Less blocking on reviews.
• Simple to roll back.

What is Small?

• The CL makes a minimal change that addresses just one thing.
• There are no hard and fast rules about how large is “too large.” A 200-line change in one file might be okay, but spread across 50 files it would usually be too large.

Keep your Branch Up to date

Keeping the branch you want to merge with master up to date will help you to avoid conflicts and to check how new changes are integrated.

Some benefits:

• Test your integrated changes with the master branch.
• Use the latest functionalities at the HEAD of the master branch.
• Avoid merge conflicts before creating the pull request.

So what to do rebase or merge?

When you merge a branch, git creates a merge commit that can be discarded or amended if the conflict resolution goes poorly. Even if you have already pushed the bad merge commit to the public/authoritative repo, you can use git revert to undo the changes introduced by the merge and redo the merge correctly in a new merge commit.

When you rebase a branch, in the likely event that conflict resolution is done wrong, you’re screwed. Every commit now contains the bad merge, and you can’t just redo the rebase*. At best, you have to go back and amend each of the affected commits. Not fun.

Summary

• Follow a good convention naming your commits and branch
• Add a good description
• Make the pull request small
• Keep your branch up to date before and after creating the pull request
• A good pull request makes a minimal change that addresses just one thing