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
Traceability in software engineering describes the extent to which code can be traced back to a planned project or initiative. A high Traceability score indicates good collaboration between Product and Engineering, and that the team is working toward agreed-upon goals.
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.