Definition
Portion of code changes that are tracked by a project management tool.
Calculation
Total % of PRs that can be linked back to a Jira issue.
We link PRs and commits to Jira tickets by checking if they contain a JIRA Issue Key (i.e. <project id>-<number>) that matches a Jira issue record in our database.
For PRs, we check the PR title (case sensitive), body (case sensitive), or head ref (case insensitive) for an issue key.
For commits, we check the commit message (case sensitive) for issue key. We also check the associated PR; if the commit doesn’t contain a key but the PR does, the commit is considered traceable.
Why it Matters
Without solid Traceability, it is difficult for the team as a whole to know if the top priorities are being worked on. This can lead to team miscommunication and missed deadlines. Low traceability can often be attributed to urgent incidents or "quick favor" adhoc asks. Traceability not only is critical for achieving business objectives but preventing engineer burnout. By making all work visible through better Traceability, product managers and engineers can openly discuss the tradeoffs of work items and focus on executing the most impactful ones.
How to use it
While some amount of untraceable work is expected, a low Traceability score could indicate some underlying issues that are important to address. Low Traceability is often caused by:
incident-driven, urgent and unplanned work,
non-incident unplanned work taken up by an engineer even though there’s no Jira issue for it, or
a failure to link related Jira issues with PRs, even though the work is planned and tracked in Jira.
If your Traceability is low, drill down into the Traceability metric to review untraceable commits and diagnose their cause.
Benchmarks
The median organization links 66% of their code changes to Jira issues. The bottom quarter of organizations link less than 41%, while the top quarter link at least 78%.
Troubleshooting Traceability: Why is my commit not shown as traceable in Velocity?
If Velocity is showing a certain commit is not traceable, use the following steps to troubleshoot:
Confirm that the commit message includes a Jira Issue Key (e.g. ENG-123). *Note: the "message title" seen in Velocity drilldowns is only the commit title (the first line of a commit message), but Velocity searches for issue keys in the entire commit message. Head here to learn how to search for commit messages.
If an issue key is not included in the commit message, confirm that the issue key is included in the related PR's title, body, or head ref (head branch name).
Confirm that the Jira issue has been ingested by Velocity. Using Analytics, search for Issues opened, and filter to the relevant project and date range. In the results, drilldown to the relevant board to view a list of all issues opened.
If the issue is not listed in the Analytics results, it's likely that Velocity hasn't ingested the issue from your Jira project. Confirm that the Jira project has been added to Velocity (via your Projects settings). If the project is connected to Velocity, but you're still unable to locate the relevant issue in the Analytics tab, contact support for assistance. Please include the name of the project, the issue key, and a screenshot of the commit message, PR title, body, and head ref from GitHub.