Tips & Tricks

A guide to making a good pull request

One Comment

When working on any project, there’s best practice in incorporating a good pull request policy for all code changes.

By introducing these into your code repositories, you open up to improvements in code quality through peer review.

Errors will be spotted easily, preventing broken changes from being introduced to your main branch. Overall, you’ll help the entire team gain a better understanding of the codebase.

Here are some tips to help you make a good pull request for your team to review.

Be descriptive in your pull request

Part of what makes the reviewing of a pull request easier is knowing what has changed and why.

For your pull request’s title, make such it describes the change in a clear but concise way. No need to delve into the details here, we can add that into the summary.

The summary is where you describe in more detail exactly what the change does. Here you can include the reasons for the implementation, and potentially how you’ve tested it.

This detail allows a reviewer to understand everything about the change and set their expectations when reviewing the code.

Link to relevant information

Reviewers won’t be looking for an essay in a pull request description. There may be key detail in a user story, issue, task, or linked document that could be of interest though.

Don’t forget to include links. This ensures that the reviewer has access to anything you think might be relevant. Where context is needed for the decisions made, this will be very helpful.

Keep the changes lean

It’s important to keep changes in a pull request to a focussed area within the solution for a specific task. Try to avoid making many changes across various areas.

By sticking to this, you’ll help a reviewer by speeding up the process of the code review. Reviews with 100s of file changes may take hours to run through and could lead to potential mistakes being missed.

Sometimes your tasks also might be too big which leads to major changes to a codebase. Break the changes up into smaller pieces of work that you can easily fit into this format.

Document breaking changes

A breaking change is something that could affect another developer’s work. For example, you made a change to a public function that is widely used by adding a new parameter.

In most circumstances, the best cause of action is to think about the change and its impacts on the solution. In the above example, you could create an overloaded method instead of introducing a parameter to an existing one.

If the decision is made to introduce the breaking change, it’s crucial to ensure to document them clearly. They should also be documented separately from your summary.

It might be useful to include steps a developer should take to fix their code before their next pull request.

Creating a good pull request with a template

All of these points are easily summarized by introducing a pull request template. Following this approach will standardize your pull request reviews across your repos.

Without structure, it’s often easy to not include a lot of detail in a pull request, or nothing at all. This is bad for many reasons, the most important being, reviewers will not know what you’ve done and why.

You might think that your code is self-explanatory, but without context, your changes might not be interpreted well.

The best measure is to create a good pull request template with headings and helpful tips to prompt its usage. By doing this, you standardize how every developer who works on your project brings their changes into your main branch.

If you’re using Azure DevOps, GitHub, or Bitbucket, you can add a template directly to your repo. Doing this ensures that the templates are used every time a pull request is created.

Are you looking for a good example template? Here’s one that I use in my open-source projects to get you started!