Improve PR Mapping to Jira Tickets

Jira provides enterprise-level functionality for tracking and managing issues, new feature requests, deprecation of old features, and all other changes to modern software. But to take full advantage of the power that it provides, issues need to be mapped, or linked, to the implementing PRs.

Why Is It Important?

By mapping PRs to tracking issues, all stakeholders, whether management, developers, or anyone else will be able to fully track an issue from creation through to completion. They will be able to see everyone who worked on it, what changes were made, the feedback made on those changes and the further changes made in response to that feedback, and so much more. 

To quote Atlassian support:

Your team gets to see their branches, commit messages, pull requests, builds and deployments right in the context of the Jira Software issues they're working on.
  1. What KPI Should You Track?

The key KPI to use to track this is the number of PRs mapped to issues. Any PRs that are not mapped to an existing issue should be mapped as soon as is practically possible.

What Are The Underlying Metrics?

There are three key metrics that can be used to track the KPI. These are:

  • Pull Requests Created. How many PRs are being created and are they being consistently mapped to Jira Tickets.
  • Issues throughput. 
  • Release frequency. 

How Do You Improve PR Mapping to Jira?

There are two key steps required. These are:

  1. Integrate Jira with GitHub. How this happens is different, based on whether GitHub Cloud, GitHub Enterprise Cloud, or GitHub Enterprise Server is being used. Regardless, refer to the Atlassian documentation for the required steps.
  2. Mention the Jira issue ID in a Pull Request’s title or body or in a commit message. For example, use a PR title such as “DEV-3515 - Correct Extended Timeout When Email Server is Down” or commit message such as “DEV-3516 - Improve site accessibility for users with Protanopia”. Both messages are prefixed with the Jira issue ID.

In addition to these two, there are a series of additional steps which can be taken. These are:

  • Break large features down into smaller pieces of work in Jira. Ideally, aim for a one-to-one relationship of Jira issue to PR. By doing so, you can ensure complete visibility on the implementation progress of every PR.
  • Ask the product team to include technical debt, maintenance, or any work contributing to the actual quality of the codebase with the Jira planning. That way, clear visibility on the amount of effort required to perform the necessary work is available and uncertainty and misalignment between the product and engineering teams can be reduced or avoided.
  • Publicly acknowledge and reward the top performing team(s) based on this metric. By doing this it will encourage other teams to do the same.
  • Make engineers owners of Jira. As part of this, engineers are accountable for keeping Jira issues in sync with the state of the work on GithHub and with the correct status in Jira.
  • Use Jira during planning and retrospective meetings. As part of these processes, ask engineers to update the applicable work.