Kin + Carta is joining Valtech. Learn more here >

Skip to main content

Select your location

Search

How to make the perfect pull request

person working at the computer

As engineers, we know that managing a large-scale project can be difficult. At any given time, there could be a number of people making changes to different parts of the project. Sure, you can communicate with different platforms or in-person but those methods have the potential to fail.

People can forget things and all of these struggles are multiplied when a project is large and we should continually add new features. What do you do to fix the problem? Well, this is where pull requests come in.

What is a pull request?

According to GitHhub, “Pull requests let you tell others about changes you’ve pushed to a branch in a repository on GitHub. Once a pull request is opened, you can discuss and review the potential changes with collaborators and add follow-up commits before your changes are merged into the main branch.”

Suppose that we have to implement a new feature for the current project, of course, based on the figure above we should have a new feature-source branch

What is branching?

Branching is a feature available in most modern version control systems. Branches are part of our everyday development process. They are effectively a pointer to a snapshot of your changes.

When you want to add a feature or fix a bug-no matter how big or small-you spawn a new branch to encapsulate your changes. This makes it harder for unstable code to get merged into the main codebase, and it gives us the chance to clean up the history before merging into the main branch.

The diagram above visualizes a repository with two isolated lines of development, one for a little feature and the other for a big feature. By developing them in branches, it’s not only possible to work on both of them in parallel, but it also keeps the main branch free from questionable code. In this way, we make sure that just after we have fully completed X feature after the code was reviewed,

What is a code review?

Code review is a software quality assurance activity in which one or several people check a program mainly by viewing and reading parts of its source code. At least one of the persons must not be the code’s author. The persons performing the checking, excluding the author, are called “reviewers”. By doing code review, we tend to have a high quality of the code, share knowledge between collaborators, find bugs easier, and recommend the best way of implementing a feature to each other.

What makes a good pull request?

Not all pull requests are well created and easy to review. If you open a pull request that contains many different unrelated changes that are out of the scope defined in the ticket, it is hard to perform a good review.

In order to get the most out of your code review process, try to minimize the line count of changes and focus just on the requirements of the ticket described. You should fulfill all the requirements and try to write clean code, instead of writing pieces of boilerplate repetitive code. Format the code before making pull requests and don’t let unnecessary empty lines.

Good pull requests contain:

  • Title
  • Description
  • Ticket URL
  • Screenshots (optional)
  • Video records (optionalThe title should be small and concise and tells the reviewer/reviewers what is implemented in general terms.

The description should tell the user the reason and the context of what is implemented in detail. This can give the reviewer a much better understanding of the problem it solves. You should include documentation or design files that rely on the ticket requirements.

In many practices you can create a description based on the questions below:
  • WHY - Which tickets/issues/proposals you are working on?
  • WHAT - What have you done?
  • HOW - What the reviewers should know?

Ticket URL should be included as part of the pull request, we do so to give the reviewer a chance to take a look at what was required for the changes that he is looking for. In some cases, based on my experience, there are chances that the reviewer does not have access to the ticket URL. In those situations, you should copy/paste the ticket requirements into the pull request description to give the reviewer a better understanding.

Screenshots can be included in the pull requests, they are recommended but not mandatory. By doing so we can give the reviewer a look at what was implemented. We can show before/after screenshots for better understanding.

Video records are recommended but not mandatory. These are very productive in situations where we have implemented a flow of screens and want to share it with the reviewer.

Below are a few reasons why creating small pull requests can be beneficial:

  • Reviewed more thoroughly
  • Reviewed more quickly
  • Easier to merge (frequent merges lead to fewer conflicts)
  • Less wasted work if rejected

 

Here are some ideas to make it easier for you to make small pull requests:

  • Extract refactoring to a separate pull requests
  • Split big features into parts(even if they wouldn’t be user-facing)
  • In case of long-running feature branches, set that branch as a target for your pull requests instead of base-branch

What is single responsibility principle?

The single responsibility principle (also known as SRP) is a computer programming principle that states that every module or class should have responsibility for a single part of the functionality provided by the software, and that responsibility should be entirely encapsulated by the class.
 
Just like classes and modules, pull requests should do only one thing. Pull requests that follow the SRP reduce the overhead caused by revising a code that attempts to solve several problems. Before submitting a pull request for review, try applying the principle of single responsibility. If this code is doing more than one thing, break it into other requests.
 

How to give feedback when doing a peer review of a pull request

When reviewing an assigned pull request, first check the title, description, and ticket URL. By doing so you get a context of what was required to implement. Check-in details the code written and leave your comments and opinions. Try to have a friendly approach and use magical words. Don’t use words like “must” or “do this”, “improve this” instead you can write down your opinions in a friendly manner: “I think it is a better idea to..”, “Please can you make this change here…” etc.

Whenever you are impressed with the code written, don’t hesitate to leave a positive comment like: “Great job”, “Awesome” or something like that.

Sum it up by leaving a comment like this: “Great job, I left some comments for further polishing, let’s discuss” 

Respond to comments quickly

Show respect to the reviewer's comments and if they ask for something try to respond as soon as you can. Write your opinions and let them know about a specific comment.

If you do that quickly, your reviewer would have to spend less time remembering what that comment was all about. Less time to merge means happier colleagues, which means more friendship. After the PR is approved now you are free to merge it into the destination branch. Congratulations on getting your task done. Take a break and get a new task.

Conclusion

To sum it up, a good pull request will be reviewed quickly so it does not block other developers, it speeds up the code review process, consequently the product development. Pull requests are the best way to keep the code clean and to have a number of bugs smaller and as the saying goes: “Four eyes see better than two”. In this way, we are on the road to success and finally, have a great product and keep the client happy.

Share this article

More like this

Show me all