3 Tips on Opening Effective Pull Requests

Featured on Hashnode

When I first started working almost 3 years ago, I couldn't see the need to include anything in the description of my pull requests. I had felt that the title is enough. In some cases, this is true. But in other cases, a Fix broken ABC feature sounds vague to code reviewers. Being provided at least some context about the pull request can be helpful.

In this article, I'll be sharing 3 tips on opening effective pull requests.

1. Describe why you made the changes

Describing our changes is a great way to provide the context of the pull request (and commit). It can be helpful now and in the future. Here are reasons why. 👇

  1. The reviewer can view the pull request from a certain angle, providing potentially better suggestions
  2. Tracking down bugs in the future are easier as we would have an idea as to why certain changes were made

2. Keep the pull request small

When a pull request is big, the reviewer can feel overloaded with information. When this happens, it can affect how the reviewer views the correlation between a piece of code with another and worse, a sneaky bug can slip through. But when exactly can a pull request be considered as big?

We can use this study as a guide and follow our instincts because pull requests are unique.

A SmartBear study of a Cisco Systems programming team revealed that developers should review no more than 200 to 400 lines of code (LOC) at a time. The brain can only effectively process so much information at a time; beyond 400 LOC, the ability to find defects diminishes.

How should we decide to keep our pull requests small? Ask ourselves this question whenever we think about fixing a bug or implementing another feature altogether.

Can this be done separately? If yes, then do in a separate pull request.

3. Write a changelog

Unlike my first two tips, this is rather insignificant. Before I started describing my changes, I tend to just include a changelog to give the reviewer an idea of what to expect. Nowadays, the changelog acts as an addition to my description. A changelog could look like this.

changelog-example.png

If you find this article helpful, please spread the word!

Do follow me on Twitter to read about my findings while programming or my feelings of joy and despair while watching football. I'm also active on Instagram and Goodreads where I frequently share what I'm reading and what I've read.

Thanks for reading! ✌️

Mohd Shad Mirza's photo

Helpful Advice. This is what has been helpful to ship a bigger feature in small separate PRs. All Sub PRs are small sub-task that can be reviewed separately.

Screenshot 2020-12-16 at 11.48.50 AM.png

Ali Ilman's photo

I’ve done something like this before!

I had an epic branch where all the code relating to the epic gets merge into that branch. Afterwards, they’re merged into main. A minor disadvantage of doing this is the possibility of conflicts which can be resolve with frequent rebases.

Mohd Shad Mirza's photo

Ali Ilman yeah, small price to pay 😄

Edidiong Asikpo's photo

I agree with creating smaller PRs; it actually helps to make the job of the reviewer easier and more straightforward as they can easily identify your changes and know it is focused on one or two changes. I enjoyed reading this article Ali Ilman.

Ali Ilman's photo

Thank you!

That is indeed the positive result of opening small PRs.