How to build better pull requests for collaboration and product development

When you have a team of engineers working together on a project, it’s common to have tightly protected version control to ensure that buggy code doesn’t make it into your master repository.

Often, a developer might work independently on a local copy of the codebase to implement a feature update. When the code is complete, they can create a pull request (PR) to request another developer to review the code for errors and then merge it back into the codebase.

Here are some tips for creating a strong PR process with your team:

Provide proper tagging for your PR

If it involves security, tag it with a SECURITY Tag. If it is a work in progress, tag with DO NOT MERGE or WIP:PROJECTNAME tags.

A PR might be seen by people outside of your company, such as customers or other companies, so use professional wording throughout. This also includes any compiled strings (e.g., Exception/Log messages), as customers might decompile the assembly.

Add additional context

If your PR is non-trivial, include a summary of why the change was required. It’s helpful to provide as much information as possible on what’s been changed in the codebase. For example, if you change something in a UI, give a before and after image.

It’s also important to include links to tech specs, and a clear description of why a change is being made. Give plenty of detail so that the reviewer understands why something is happening—don’t make assumptions; months in the future, no one will remember why you chose to do things a certain way without the necessary background information.

Publish your PRs outside of your code repository

While your engineers might typically keep all PRs in GitHub repositories, others within your organization may also need access to contextual information around feature releases for their own purposes. Instead of keeping PRs siloed, share them more broadly with your entire organization through a knowledge-sharing platform, where anyone in the company can ask questions about and add context to your existing PRs.

By taking steps to make your engineers’ PRs as thorough and transparent as possible, you can help to facilitate seamless collaboration between teams to increase the velocity of your product development.

What to read next