On this page
Research context
Review turnaround is one of the easiest engineering numbers to produce and one of the easiest to mislead with. This protocol fixes the clock, the population, the strata, and the quality pairing before any pull request is counted, so a later reviewer can rebuild the same result from the same events. The purpose is a decision aid about queue design, not a score for a person.
The question is descriptive: for a declared repository and period, how long do eligible pull requests wait between the start event and the first substantive review, and who owns that wait? It is not a question about individual productivity, and the readout should say so in its first paragraph. A measurement that is used for a purpose it was not designed for will produce confident answers to the wrong question.
The population is pull requests in one repository that became ready for review during the window and were eventually merged or closed. The observation unit is one pull request with its full event chain. Draft periods, abandoned branches, and automated dependency updates are handled by explicit rules rather than silently included or excluded, because the choice changes both the count and the median.
Start and stop events must be declared. Common choices are ready for review to first review submitted, or opened to approval. Each produces a different number and a different story. Pick one primary pair, publish the definition beside every chart, and keep any secondary pair clearly labelled rather than mixing them in one line.
Counted hours need a rule. Elapsed clock time is simple and includes nights and weekends. Business hours need a time zone and a holiday calendar. If the reviewer and the author work in different zones, state whether the clock follows the repository, the author, or the reviewer, because the same event can move by a full working day depending on that choice.
Build the event table from the platform rather than from memory. Required fields are pull request identifier, author role, ready time, first review time, review state, approval time, merge time, change size, files touched, and whether a protected path was involved. Bot events are marked, and each event keeps its actor so the later analysis can separate a reviewer from an automation account.
Define a substantive review. An automated comment, a label change, or a one word approval is not the same event as a review with comments that led to a code change. Record the definition and count the borderline cases separately, so a reader can see how much of the result depends on whether a rubber stamp counts as a review.
Practical application
Strata make the number interpretable. Report by change size band, by protected area, and by whether the pull request was a re-review. A median across all sizes hides the fact that large changes wait longer, and a target applied without strata rewards splitting work into trivial pieces. Size bands should be declared in lines changed or files touched, not by a subjective label.
Wait ownership is the useful output. Split the interval into author hands, reviewer queue, rework, dependency wait, and merge approval wait. Do not add overlapping intervals. The dominant cause is the only part a manager can repair, and it is often a queue design problem rather than a person moving slowly, especially when one reviewer holds most of the protected area knowledge. A reviewer who holds most of the context for a service becomes a queue of one, and the protocol should show that concentration as a system risk rather than as an individual trait. When the same name appears on most reviews in a stratum, the repair is a second reviewer with enough context, not a reminder to work faster.
Re-reviews need their own interval. A pull request reviewed quickly and then returned three times is not a fast review. Count the number of review rounds and report the median rounds beside the first review latency. A team that improves first response while increasing rounds has improved a metric and not the flow.
Time zone handling should be tested with a known case. Take a pull request opened late in one office and reviewed early in another, then compute the interval under both conventions. If the two answers differ by a working day, the readout must say which convention it uses, and the published number must not be compared with a report that used the other one.
The denominator is every eligible pull request in the window. Report the count, the exclusions with reasons, and the number with a missing event. A percentage without the eligible count is not reproducible, and a missing event is not a zero. Silent imputation is how a report becomes a rumour.
Pair latency with a quality signal. Options include post merge defects linked to the pull request, review comments that changed the code, and rework rounds. Fast approval with no comments and a later defect is a worse result than a slower review that caught the issue, and the protocol should prevent the chart from implying that the fastest queue is the best one.
Check for gaming patterns before publishing. Watch for very small pull requests opened to reset a clock, approvals by reviewers who did not open the diff, and review events split to create an early timestamp. These patterns are visible in the event table and belong in the caveats, not in a private note that disappears when the analyst changes role.
Operating controls
Independence is limited but useful. Have a second analyst recompute one week from the raw events and compare counts, not only medians. A median can match while the underlying eligibility differs, which means the definition is not stable enough to survive a change of analyst or a question from a sceptical reviewer.
Report a distribution, not only a centre. The ninety fifth percentile and the count above the target carry more decision value than a median. A service target that is met on average and missed on the urgent path is not met, and the urgent path is usually the one the customer notices.
Holidays, incidents, and platform outages distort short windows and can move a monthly median by hours, so the chart should label each one rather than leaving a reader to infer it from an unexpected dip. Either exclude them by a written rule or publish the effect. Silent exclusion looks like manipulation when a colleague recomputes the period, and a written exclusion with a visible effect is much easier to defend.
Access and privacy rules apply to the extract. Pull request metadata can reveal project names, customer names in branch titles, and individual working patterns. Use least-privilege access, redact titles in published tables, and set a retention date for raw event data. A dashboard that is convenient to build and impossible to retire becomes a permanent copy of staff activity.
The method has clear limits, and every published rate carries its denominator. It describes one repository in one period under one clock definition. It does not measure review quality, does not establish that a turnaround target improves delivery, and does not support a comparison between individuals or between outsourced and in-house staff. Run a sensitivity check on the clock and the strata before drawing a conclusion: recompute with elapsed hours, with drafts included, and with the largest size band removed. If the conclusion flips, present the range and name the decision that depends on the choice.
The practical output is one change to the review system: a reviewer rotation, a scheduled review window, a smaller default change size, a clearer template, or a named backup reviewer. State the expected signal and re-measure after the change rather than declaring success from one month. Keep the target advisory, because review latency is shaped by queue design, change size, reviewer availability, and the number of concurrent requests. Acceptance is reproducibility: another analyst should rebuild the extract from the recorded query, reach the same eligible count, apply the same exclusions, and explain any difference. The company owner retains the decision about targets, staffing, and whether the number is used at all.
Sources
Frequently asked questions
What should happen first?
Begin with a bounded ticket, approved access, explicit acceptance evidence, and a named reviewer.
Who approves production changes?
The client's technical owner keeps final merge and release authority.