Better Pull Request Management with Custom Labels

GitHub has some neat features for managing pull requests, but sometimes it’s tough to quickly get a high-level status for each request.

To improve this workflow, we’ve implemented a custom labeling pattern for pull requests on some of our code repos.

Using GitHub Labels, we mark the state each PR is in, so that it’s clear where the Pull Request is at in its flow.

The Main Flow

Almost all PRs move through the following cycle:

1. Code added/updated, needs review
2. Code reviewed, needs update
3. Repeat as necessary until good to merge

We mark where the PR is in the cycle with the following labels:

PR: Needs Review

After opening a Pull Request, you’ll likely want someone to review it. Mark it with the PR: Needs Review label to identify to others on your team that your PR is ready for review.

PR: Reviewed w/ Comments

After the initial review, most PRs are left with a few comments/questions about the changes. As a cue to the original author that you’ve passed through the changes and have finished your thoughts, the reviewer removes the PR: Needs Review label (if applicable) and adds PR: Reviewed w/Comments.

Next, the submitter responds to the comments and updates the code as necessary. They then begin the cycle again by adding PR: Needs Review and removing PR: Reviewed w/ Comments.

PR: Good to Merge

At some point, the PR should be good to go. To help avoid any ambiguity in state, the reviewer should mark the PR as PR: Good to Merge. This lets the author know that their code is fully accepted by the team.

After merging, the labels can be left as is. The Pull Request is complete and won’t need updating again.

Other Scenarios

There are a few special cases that deserve their own label. They don’t come up as often, but are good to have around when needed.

PR: Needs Manual Merge

Sometimes PRs get out of date with the main branch and need a manual merge. GitHub will let you know this by greying out the “Merge” button, but it can be helpful to mark this via a label so the team can easily know the status of the PR.

PR: Merge on CICD Pass

For small PRs, or PRs reviewed and small updates applied, there are times when the code has been reviewed but the CICD task hasn’t completed yet. A reviewer can mark the PR as good to merge with the condition that the build passes by using the PR: Merge on CICD Pass label.

DO NOT MERGE

There are times when you have some experimental work in the form of a PR that you’d like to open up for review. Ensure it doesn’t accidentally get merged in by adding the DO NOT MERGE label. While this doesn’t disable the “Merge” button, it should be a red flag to anyone reviewing the code not to merge it in.

On Hold/Work in Progress

For when you want to put some future functionality out there for review, or an unexpected blocker arises during the PR process, or you just need to wait until another PR goes through, the On Hold and Work in Progress labels help reviewers know the status of a PR that isn’t progressing in the workflow.

Using this label is helpful in avoiding review fatigue, where PRs seem to die out unexpectedly. At least now if they die out, reviewers aren’t left wondering the state of the PR. They know to just let it sit until time is found to continue work on the PR, or the PR is closed without merge because circumstances changed.

Similar to the “DO NOT MERGE” label, you can also update the title of the PR to be extra clear of its current state.

Challenges

There are two major challenges with this system:

1. Newcomers won’t be familiar with the convention and may not follow the steps. It usually doesn’t take much effort to get everyone up to speed, but it can be confusing when people forget to update the label.
2. The labels have to be manually added to every Github repo, as the defaults aren’t configurable. It’s tedious to take this step when you’re just trying out a new idea and also makes it difficult to validate the convention is being followed across all repos.

One way to overcome both of these drawbacks would be to add a PR Review bot, which would help set up and enforce the labelling. Something similar to MentionBot. In fact, this is something we hope to look at in the near future using the Github API.

There’s certainly always room for improvement, but using this pattern for our PRs has already paid off. Give it a shot and let us know if there are any labels you think we should add to our bucket.