Code Review Cycles

DEFINITION

Code review cycles measure the back-and-forth interaction between a pull request author and their reviewers. A review cycle begins when a reviewer provides feedback (comments or a change request), and it ends when the author responds by pushing new commits.

This metric serves as a valuable proxy for understanding the amount of effort and context switching required to get a pull request approved. A high number of review cycles can indicate unclear requirements, complex code that is difficult to understand, or a lack of alignment between the author and reviewers.

HOW IT’S MEASURED

We determine the number of review cycles by analyzing the chronological sequence of commits and reviews. A review cycle is review followed by any subsequent commit. For example:

1. A pull request that is opened, but not reviewed, does not have any review cycles.
2. An approval followed by merging a branch is one review cycle.
3. A comment followed by two commits is one review cycle.
4. The final approval counts as one review cycle.

Here is a summary of the commits and reviews that are excluded from this calculation:

• Author's Own Reviews: Comments and reviews made by the PR author on their own work are ignored.
• Activity Before "Ready for Review": Any commits or reviews that occur before a pull request is marked as ready for review (i.e., taken out of "Draft" status) are excluded from the calculation.
• Bot and AI Reviews: Reviews from users identified as bots, such as linters, security scanners, or AI code review tools, are excluded.
• Open-Source Contributor Reviews: Reviews from individuals who are not members of your organization are excluded.
• Merge Commits: The final merge commit is not counted as part of a review cycle, as it occurs after the final approval. The final approval counts as the last review cycle.

Other considerations:

• Commits by Other Authors: commits are not limited to the pull request author. Commits created by other members of your team can complete a review cycle.
• Post-Approval Activity: Commits and reviews that happen after the first approval but before the PR is ultimately merged are included in the cycle count.
• Manager Reviews: Reviews from users whose authored pull requests are excluded (e.g. managers, product managers) count towards review cycles.

Why are bot and AI reviews excluded?

We exclude reviews from non-human sources to keep the metric focused on the human element of collaboration. The goal of Code Review Cycles is to measure the friction and context-switching between team members.

Counting automated reviews from linters or security tools can arbitrarily increase the metric, making it less actionable for process improvement. With the rise of AI code review tools, developers should not see their metrics negatively impacted for using modern tools that help them improve code quality before human review.

This approach maintains consistency across all Software.com metrics (e.g., Time to Review, Code Review Participation), which are focused on the human aspects of the development lifecycle.

Can I spot check Code Review Cycles for a pull request using the GitHub/GitLab UI?

Yes, in most cases, depending on how commits are added to the pull request. 

A workflow in which a developer rebases their branch locally and then force-pushes their changes rewrites the branch's commit history, updating the timestamps and order of commits. As a result, the sequence of events shown in the UI may not reflect the actual back-and-forth that occurred between the author and reviewers. Software.com uses the true event timeline to provide an accurate calculation.