A big part of what makes GitClear useful to teams is the integration into popular issue trackers like Jira and Github. By default, GitClear can detect references to external issues once you have set up a tracker connection. But sometimes your team will refer to issues in some way that isn't mentioning their full external issue ID (e.g., something other than BUG-123 or BUG123, both of which would be detected automatically if you have a Jira project called "Bug"). In these cases, Repo Issue Mapping can allow you to set up advanced rules that connect your commits, branches and PRs back to issue tracker tickets.
linkCreate a Repo Issue Mapping by Providing "Issue Reference" and corresponding "Project Key"
The basic idea for Repo Issue Mapping is that you prescribe a symbol or regular expression that gets paired with a number. Here's how it looks in its default form:
Creating a new Issue Mapping that recognizes when the identifier "B" precedes a number, and translate that to an issue tracker key of "BONANZLE". The right box will show how many commits would match the "Issue reference" you've provided.
If the user clicked the "Create a new issue mapping" in the screenshot above, then GitClear would commence to search all commits, pull requests, and branches in the repos that the Repo Issue Mapping is available to (about 20 repos in this example). At the end of that process, about 50,000 commits would be assigned to a repo issue in a tracker project. 🎉
When you declare an "Issue Reference," it will match a variety of formats that developers may use to refer to the issue. As an example, let's use the "B" as the "Issue Reference," as shown in the screenshot above. Finding any of the following inputs in the commit message, pull request title/description, or branch name, would connect the commit to an issue:
I'm working on b123
[B-123] Is resolved by this commit
This PR solves Issue B#123
branch-b-123-implements-cool-feature
If you find false positives connecting commits to issues, you can either encourage developers to adopt a more distinct "Issue Reference," or you can consider writing your own regular expression as discussed below.
linkFor Jira users
For Jira users, the best first step is to ensure that your repo has been connected to Jira. After you've done that, GitClear will scan your commit titles for patterns that correspond to the project keys you've setup in Jira. If we find a match, we will automatically create a Repo Issue Mapping on your behalf.
If we find what looks like a common pattern in your repo, but we can't find a corresponding key in Jira, then the proposed Repo Issue Mapping will show up as a suggestion when you visit the Settings -> Issue Tracking page.
linkBenefits of pairing commits and issues
Many areas of GitClear work better (or work at all) when commits can be tied to issues.
linkCommit Activity Browser
The Commit Activity Browser can color its contents based on the issue being worked on:
Commit Activity Browser can color commits by the issue they resolve (enabled in the screenshot - this can be controlled via the "Color" link in lower right). Hovering on the label for an issue will give rich details about the issue and the work that has gone into it.
Even if your commits aren't colored by issue, you can still easily identify work that isn't dedicated to an issue by looking for the circles that have crosses through them: those are the commits that weren't related to any issue.
The percentage of commits that don't work on an issue can be a very illuminating metric to establish a sense for. If you're a manager that has been frustrated at the slow pace of closing tickets, it might be because most of the work being done by the team is toward undocumented tasks. Discovering the "undocumented requirements" your developers spend time on can help you make more realistic project planning estimates. It can also help identify whether the non-issue work can be reduced.
The amount of non-issue work varies according to team size. Teams of 3 or less often spend 50% or more of their time working on non-issue commits. Teams at Enterprise companies may be prohibited from spending any time on undocumented work. The optimal policy depends on the company's circumstances.
linkRepo Issue Stats
Repo Issue Stats show how much work is going into different types of tickets over time. Has there been a surge in the amount of bug work lately? Repo Issue Stats makes it clear
Repo Issue Stats are an especially useful tool if you perform annual reviews of your developers and you want to quickly recall the biggest, most important tickets they worked on during the past year. Visit Issues -> Stats with a particular developer filtered and you can recall the results of this developer's biggest projects over the past 12 months, and how customers liked the result.