Home Home

Identifiers in bug tracking systems

Arseni Mourzenko
Founder and lead developer, specializing in developer productivity and code quality
134
articles
January 17, 2019

One annoying aspect of bug tracking systems is the identifiers.

In systems such as Jira, every time a ticket is created, an identifier is assigned to it. The identifier is based on a number which increments every time. For example, I create two tickets in project TEC, I may end up with TEC-512 and TEC-513. Those identifiers are then used to reference the ticket, both inside the system itself, as well as from other sources, such as version control commit messages.

The problem with those identifiers is that they are based on an information which is mostly useless. Imagine I'm working on TEC-512 and TEC-63. What does it tell you? Only that the second one was created before the first one. How would such information be relevant?

Another problem—which is mostly the consequence of the first one—is that it's damn difficult to remember them. Imagine that I'm fixing a bug where the data change messages sent to an MQS are not encoded correctly. I may guess that the ticket called “Change the encoding to UTF-8 for data change events sent to RabbitMQ,” or I may find it based on the fact that I'm assigned on this ticket, or that it was initially created by Robert, or that it was active yesterday. But if all field except the identifier are hidden from me, I'll never be able to guess that my task corresponds to TEC-402.

Is there a better way to reference a ticket?

For internal usage (i.e. cross-references within the bug tracking system itself), titles are ideal. Compare:

According to the logs, occasional crashes are due to the fact that the script is unable to recognize the names of the users. Since it happens only for the users with names containing characters outside [A-Za-z] range, I suspect this to be related to TEC-402. Let's wait for this other task to be solved first, and then Vanessa will decide what behavior is expected in a case where the name of the user is not recognized (for instance of the user was removed from the system).

to this:

According to the logs, occasional crashes are due to the fact that the script is unable to recognize the names of the users. Since it happens only for the users with names containing characters outside [A-Za-z] range, I suspect this to be related to the ticket “Change the encoding to UTF-8 for data change events sent to RabbitMQ.” Let's wait for this other task to be solved first, and then Vanessa will decide what behavior is expected in a case where the name of the user is not recognized (for instance of the user was removed from the system).

See? In the first case, there is information missing, and I have to click on the ticket identifier to open the actual ticket in order to find what is it about. In the second case, it's not that I have all the information, but somehow I don't need to do an extra click any longer most of the time.

For external references, things are more difficult, and two cases should be discussed.

The first scenario involves a copy-paste. For instance, to link the ticket TEC-402 to a commit in a version control, I can go to a bug tracking system, manually copy the identifier, and then paste it to the command line. In this case, nothing prevents me from copy-pasting something different than the identifier; for instance, a button near the title of the ticket may invite me to copy it to the clipboard, and then I can paste it to the terminal. Titles change, which means that it is needed to (1) keep a history of all the titles used before, in order to be able to find it later; additionally, (2) one needs to handle conflicts: a ticket shouldn't be able to have the same title as a previous (and now unused) title from the past.

The second scenario involves typing. Say I have the bug tracking system on a monitor, and my terminal on another monitor. It would be faster to just retype “TEC-402” in the terminal, rather than to switch windows and do the copy-paste. However, it would even be easier to allow me to type the beginning of the title of the ticket. Since “Change the encoding to UTF-8 for data change events sent to RabbitMQ” is obviously too long to type, the only thing which is needed to be able to identify it is something which removes ambiguity. For instance, “utf8” would be such text if there are no other recent tickets mentioning UTF-8. Similarly, “change encoding” or “rabbit” might be largely enough for the task.

Not only does it make it easier to reference a ticket for which I know the name, it also makes things easier when I don't know the title. If I'm fixing a bug where the data change messages sent to an MQS are not encoded correctly, I may type “encode mqs,” which should be close enough to find the ticket, although it requires a bit more smartness from the bug tracking system, which should know that RabbitMQ is a MQS.

Would it work with a system containing thousands of tickets? Absolutely. While it is likely that among those thousands of tickets, a few dozens or even hundreds are about RabbitMQ, most will be too old or not assigned to me. In other words, the system can start by looking at the tickets I'm working on. If it finds nothing (maybe I forgot to assign myself?), it should take a look at the tickets with recent activity. If there is still nothing (a situation which would usually happen a few times per year), the system may need some clues from me to identify the ticket.