An engineering manager’s primary goal is ensuring their team delivers software smoothly. We usually track our progress towards this goal with the key metrics of throughput and time to close, but if we want to improve these metrics, what are our options? By identifying key indicators that are upstream of these metrics, we give ourselves tools with which to improve. Today I’d like to discuss one such metric: dormant pull requests. By identifying, tracking, and resolving dormant PRs, we can not only deliver software faster but also improve our team's cohesion without burdening ourselves.
What’s a Dormant Pull Request?
A pull request has gone dormant if some amount of time has passed since it was last acted upon. It then remains dormant for a short period of time, after which it’s considered not dormant but stale.
Dormancy should begin around 24 hours after the last moment of activity and end 48 hours hence (ie, 72 hours from the last moment of activity). You may find different numbers work best for your team. In all cases, we can say a few things about dormancy:
- Dormancy does not begin immediately; it occurs after some time has passed.
- Dormancy expires. Dormancy is defined as that brief window when an issue is still relatively easy to solve. Once the window closes, the issue is no longer dormant. It’s stale. Festering.
- “Activity” could mean a number of things - the last comment, the last commit, the last approval, whatever. It should be a human activity that touches the PR, not an automated activity like a test run.
- Addressing the underlying holdup will never be easier than while the PR is dormant.
Let’s look at some examples.
- A PR is opened on Monday at 3:30pm. If no one has commented on or approved it by Tuesday at 3:30pm, it’s dormant. On Thursday at 3:30pm, it’s stale.
- A PR is opened on Monday morning. Suggestions ensue, and on Tuesday at 5pm the author pushes new commits to address the feedback. No one responds. On Wednesday at 5pm, the PR is dormant, and on Friday at 5pm it’s stale.
- A PR is opened on Wednesday afternoon. A discussion follows on Thursday and Friday, but the weekend interrupts things. On Monday afternoon the PR is dormant. The weekend doesn’t count towards the dormancy timer, but your team has had 24 working hours (part of Friday and all of Monday) to pick things back up.
Why doesn’t dormancy begin immediately?
A PR should not go dormant immediately because healthy cadences allow for some time between a when feedback is left and when that feedback is addressed. One feature of dormancy is identifying when you should take action; you should not pester your team every five minutes to see if the author has seen the comments. It will waste your time and annoy the team. It’s crucial to give your team room to breathe. And give yourself a break.
Why does dormancy expire?
Dormancy is the window of opportunity to address a nascent problem while it’s still small and fresh. The dormancy concept accepts that "small" and "fresh" are relative to how much time has elapsed, and thus dormancy itself is also relative to how much time has passed.
Dormancy is essentially a measurement of entropy, which is always increasing. Pull requests are not created and merged in a vacuum. They’re worked on by human beings whose brains forget details over time and struggle to switch contexts. They’re opened along with many sibling PRs that also clamor for limited attention. If a PR stays open for a while it’s likely to need to be rebased off the advancing merges, entailing frustrating and time-consuming merge conflict resolutions. All of these issues are exacerbated by the passing of time. They get worse - and more costly to fix - the more time that passes.
Dormant vs Stale
Once dormancy expires, the PR becomes stale. A stale PR is a big problem and is at increasing risk of not getting merged at all. Indeed, sometimes the best thing to do with a stale PR is simply to close it, as languishing pull requests exert a significant mental tax on the team. Causes of stale PRs include:
- poor time prioritization of an individual contributor
- bad team dynamics, evidenced by hostile or aggressive or nitpicky comments
- poor specifications or newly discovered corner cases which require the input of other stakeholders (team leads, product managers, etc)
These issues require Heavy Managerial Intervention to address. A PR usually goes dormant because somebody forgot about it. However, all stale PRs start off as dormant, and if the underlying cause of the delay is something as serious as two team members in conflict, then the sooner you find out about it the better. Think of dormancy as the canary in the coal mine.
In all cases, the longer a PR sits, the more the problem compounds and becomes difficult to solve. Identifying and addressing an issue early on yields huge efficiency wins down the road in the form of problems you don’t have to solve.
Addressing Dormancy
Step one is to establish the time window of dormancy and communicate this to your team in writing. It's critical to set the expectation that engineers should regularly check in with open PRs and merge them within the target window.
Step two is to set some cultural practices:
- engineers should prioritize addressing feedback and merging their open PRs before they start a new ticket
- engineers should begin and end each day by reviewing their colleagues’ open PRs
- engineers should look to see if any open PRs need review or approval before beginning new tickets
Step three is to set alerts for your team that trigger as soon as a PR goes dormant. These alerts should be PR-specific, ie, do not spam your team with a list of all dormant PRs because the list will rapidly become noise. An hour later, if the PR is still dormant, you should get alerted too. If you get an alert, the team hasn't resolved the issue on their own and it's Time to Investigate. Remember, PRs usually go dormant because of simple oversight, so it's best to inquire about the status in the spirit of curiosity rather than interrogation.
Even if a resolution is not forthcoming, we gain a win by having our team continually touching PRs. Simple actions like commenting or pushing small commits help individuals retain context on the problem which helps reduce overall time to close.
By identifying dormancy and communicating this to your team, you can instill a self-correcting culture. You’ll be surprised at how quickly velocity will increase when attention is paid to this leading indicator.
Benefits of Tracking Dormancy
The obvious win is getting the PR merged. But the benefits of reducing dormancy run deeper and are more subtle.
Your team benefits from clear expectations
It’s easy to say “merge your pull requests as soon as possible,” but when a slowdown inevitabely happens, how do you hold people accountable? Most teams do not have stated expectations of when to review open pull requests, or how long is Too Long for a PR to be open. Without clear policies on how long a PR should be in review (1-3 days), behavior relaxes and delays ensue. We manage from the hip instead of according to plan. Fingers get pointed, excuses crop up. Our boss wonders if we are just making it up as we go.
Establishing a dormancy metric is a great way to encourage virtuous behavior. When everyone knows that PRs should be touched every 24 hours and merged within three days (hopefully sooner!), they will create good habits of promptly addressing open issues. And when they don’t, it’s easy to hold them responsible to an explicit policy.
Some PRs will take longer than this time frame for good reasons; they should be few and far between. Because they are exceptions to the rule, you can give them the special attention they deserve. If many pull requests extend beyond this window, you have a clear sign of deeper systemic problems that need investigating.
You Gain Compounding Time Investment
A startup’s most important resource is time. Money can be raised, team members can be hired, but time is limited. How you allocate your time is the most important decision you make. To mix metaphors a bit, a minute saved is a minute earned. One easy method of saving time is to prevent issues from happening. A five minute product pow-wow can save hours of time during implementation. Similarly, proactively addressing a lagging pull request saves hours of firefighting, not to mention stress. Many teams waste energy cleaning up messes that could be put to use building cool new features. A happy team is a productive team, and a happy manager is a fair manager.
Some leads advocate for raising an alarm when a pull request has gone stale. That’s too late in the game - the damage has already been done. The best time to raise an alarm is the moment the PR goes dormant. That moment it is the easiest it will ever be to right the ship and unblock your team. The longer you wait to resolve the issue, the more expensive the fix.
Being in the habit of resolving dormant PRs is like adding compound interest to your time account. With each PR closed, you can think “add 6 hours to the bank.”
Wrapping Up
In an ideal world, no pull request ever goes dormant. They are cleanly merged in short order. Here in the real world, we as managers must be on alert to address lagging PRs.
Tracking and resolving dormant pull requests will yield outsized productivity gains. Merges will go through faster and your team’s capacity will grow. Your team will also benefit from the structure of having guidelines and stated expectations for merge cadence.
