Is a Ticket Waiting on Code Review Blocked?

The test I use now: a ticket waiting on code review is blocked when nobody holds the next move, or the person who holds it can't start. You can see it on the pull request. The last thing that happened got no answer, and nobody has said they'll pick it up. Until then the ticket is queued, however long it takes.

The flag is the less interesting part. When a review wait does turn into a block, a yellow card tells a retro almost nothing two weeks later. The reason does, if somebody writes it down while it's still known. I got to both of these from two pull requests of mine that went badly in different ways.

Two weeks of review, and never quite blocked

A while ago I was working in another team's codebase, which meant I needed their review. I asked, and the first round came back in about two days. Then I handed it back, and for the next week it went back and forth: a question from their side, an answer or a code change from mine, another question. By the time the whole thing was finished, two weeks had passed.

Was the ticket blocked during those two weeks? By the test, no. Every question got an answer and every answer got a reply. The next move was always with someone who was going to make it. It kept changing hands, and each hand-off came with a wait too small to flag on its own. The time between actions added up anyway, and by the second week it felt like being blocked, even though I couldn't have pointed at the moment it started.

I still wouldn't flag it. What I'd do differently is leave one line on the ticket when it closes. "Review took two weeks" says nothing a retro can use. "Review in another team's code, first pass two days, then about a week of back and forth" points at the team boundary, and that's something two teams can actually talk about. This is also why who owns the next move on a pull request matters for the ticket and not only for the PR. Here the owner changed every time someone answered.

When waiting on code review is a blocker, and it was my fault

The other one is less flattering. I opened a large refactor, the fundamental kind: thousands of lines, a few hundred files. The quality gate was green. Nobody opened it.

Nobody said they wouldn't review it either, which is the part I didn't read correctly at the time. It sat for a week with no comments at all. When I finally got people to look, they pointed out what should have been obvious from the file count: it couldn't go in like that. I spent another week splitting it into more than ten smaller pull requests, and once those were up, we got through all of them in about two days.

That week passes the test easily. The reviewers held the next move and couldn't start it, and nobody said so. If someone had flagged the ticket with "waiting on review", it would have pointed a retro at the reviewers. What kept them out was the size of the change, and the fix for that was on my side. The line I'd want on that ticket now is something like "too big to start, split into 10+ PRs, then two days". (Splitting has its own coordination cost, by the way. I wrote about that in reviewing stacked pull requests.)

What Jira's flag keeps, and what it loses

Jira's flag is a yes/no marker. Atlassian's documentation describes it as a way to show a work item is important or blocked, and the card turns yellow. You can add a comment when you set or remove it, but the comment is optional. There's a suggestion on Atlassian's public tracker from November 2021, still at "Gathering Interest", asking for admins to be able to make it required.

Since nothing makes the comment required, nothing stops a flagged review wait from being a yellow card with no reason at all, or a reason in a comment nobody reads again. By the retro the card isn't yellow anymore, and what people see is a ticket that took two weeks, and a team trying to remember whether that was the reviewer, the other team or the change itself.

Flagging every review wait wouldn't help either. With the whole In Review column yellow, a flag stops telling anyone which ticket to look at. I'd keep the bar where the test puts it and spend the effort on the reason.

"Waiting on review" covers at least the two cases above. One was a team boundary where every round trip cost time. The other was a change nobody could start. There's also the case the label suggests, a reviewer who's simply overloaded. They need different fixes, and "blocked: review" on its own reads like the last one.

Where the tools I build come in

I build tools on both sides of this, so read the next part knowing that.

On the pull request side, PR Flow's review queue splits your pull requests into what needs you and what's waiting on someone else, and a waiting one says who holds it, for example waiting on author or waiting on review. In the other-team case, every question they left on my pull request would have put it back under Needs you. It shows who has the move now. It doesn't keep a record a retro could read.

On the Jira side, Impediment Ledger for Jira asks why when an issue is flagged, and keeps the reason, how long it was blocked and what resolved it after the flag comes off. A Jira admin can add the team's own reasons next to built-in ones like "Review / internal capacity". It's waiting for Atlassian Marketplace approval right now, so for now there's only its page to read. The two don't share data, and I'm not sure yet whether they should.

Neither would have fixed my refactor. The Ledger could have recorded "too big to start", but only if someone had flagged the ticket, and I didn't understand the reason myself until that week was over. An overloaded reviewer stays overloaded whichever tool shows it. And the Ledger only sees what somebody marks as blocked, so by my own test the two weeks with the other team would never have reached it. That's the case I'm least settled on. The test says it wasn't a blocker, and two weeks for one review still seems like something a team should be able to see afterwards.