While at Haven, I thought we had a pretty good system for tracking the current status of a given pull request. In this post I’ll document some of the labels that we used, what they meant, and how they helped us collaborate.

Labels For A Leaner Workflow

One of the challenges of working with pull requests is that they can sometimes take a long time to get merged in. Some of this can be mitigated by keeping pull requests small, some by reviewing pull requests as soon as possible. However, a lot of time passes while waiting for someone to review or respond to comments, or even know that there is an issue or question that needs to be addressed.

Why do we care about reducing cycle time of pull requests? It is work that is almost finished. If we can finish it, we reduce the overall work inventory in the system. It helps us get business value more quickly and learn what doesn’t work.

Labels can clarify where a pull request stands. I see the clear next step and whether I am responsible. If something needs review, I review it. If one of my pull requests can be merged or needs changes, I do these.

The Labels

I’ll cover the basic labels that I thought were most helpful, and how we thought of them. We didn’t start with all of these; we just built them up over time and revised as necessary.

“work in progress”

“This isn’t ready for review, but I want to make it public.” It might be just to get code off of my machine in case something bad happens to my laptop, or it might be work that I want help or have questions on. By pushing code up early, we can communicate with actions rather than words. Instead of “I’m working on X”, you can let commits do the talking.

“fast track requested”

“This is time-sensitive or important. If between tasks, strongly consider reviewing this first.” This label gets high priority work through the system more quickly.

“dependent on other open PR” and “has dependent PR”

In the course of developing a feature, I might need to make changes A, B, and C that build off of each other. I push up A and am working on B and finish that as well. When I make the pull request for B, it is hard to see the changes I made, since they are usually mingled with the changes from A as well.

So these labels indicate that work is stacking up and it would be nice to review faster. They also lead the reviewer to look at them in order. Reviewing the first pull request makes the diff for the second one easier.

“don’t merge”

“This PR has some sort of critical issue or I still need to do something important on it, so please don’t merge this.” It is nice to be able to keep the pull request open but still have this agreement.

“blocked”

“We are waiting on something that we can’t resolve just as a development team.” Maybe we need feedback from marketing. Maybe an external vendor’s API is not documented well enough, so we can’t proceed until they get back to us with a clarification. It’s nice to know when something can’t move forward, because we can move on to other things and check back at a regular interval.

“has conflicts”

“This PR has some merge conflicts.” This fact is not always apparent by looking at the pull request overview page, so it just makes it a little clearer that there is some work the author needs to do to make it ready to merge.

“has test failures”

“The build appears to be broken on this branch.” It might be an intermittent, but more often we have looked at the build and there appears to be something related to the changes made.

“help wanted”

“I might need some help or assistance with this pull request.” Maybe I am going on vacation and will be gone for a week, so it would be nice for someone else to take up this cause. Maybe I’m not sure how to proceed with a challenge that I am facing.

“low priority”

This might indicate a development environment experiment or something else that is lower than average priority.

“question”

Someone has a question about this PR. :) Useful for indicating that help or feedback is needed to move the ball forward.

“ready for review”

“I think this is ready for another set of eyes.” If you might have pull requests that are in progress or being modified by the author, it’s helpful to know that something is officially ready for review.

“merge at will”

At least one person thinks this code is mergeable when the committer hits the merge button.

I like leaving merging in the hands of the original author because it’s kind of fun pressing the merge button, and also because there have been at least a few times where I think late at night: “wait, what about <this crazy edge case that I just thought of>” and want to fix it before it is merged.

“recycling changes”

“I’m working on addressing the issues you raised and responding to questions you asked.” Letting the reviewer know that they have been heard and replying to their comments and pushing up again and marking as “ready for review” when the changes are implemented.

“reviewed”

I have looked at this as much as I will probably look at it for now, and it has a few comments to recycle.

“tests are needed” and “tests would be nice”

The first is a strong opinion, the second means that it might be nice to do, but not required. I find this helpful since it gets people thinking about writing tests.

“small :)” and “micro! :)”

“This thing is small and you will feel good about looking at it!”

It’s nice to indicate that something will be a quick win and easy to review. The mindset of tackling a few hundred line diff is much different than that of approaching a ten line diff. I generally used “micro” to indicate a line or two of changes, and “small” to be around ten lines of changes.

I still like pull requesting even small changes because it helps ensure fewer mistakes and keeps everyone involved with what is going on. Which leads us to…

“cowboy merged”

“It was critical to get this code into master to fix an issue or I needed it to do additional work.” As just mentioned, the default is to pull request all changes. This label means this PR was merged directly to master without review, and you can peruse it at your convenience.

Comments are still useful!

Just setting a label and leaving is often not the best team interaction pattern. Making a comment about why you are changing the status or state of a pull request is often helpful. When marking as “merge at will”, giving a thumbs up and/or words of encouragement are still good form. :)

Comments are also easier to see than label changes. Usually GitHub comments will come across on chat applications like Slack or email, but label changes are less likely to do so. So this also helps communicate more effectively.