Identifiers in bug tracking systems

Arseni Mourzenko
Founder and lead developer
161
articles
January 17, 2019
Tags: interaction-design 8 user-experience 9 short 48

One an­noy­ing as­pect of bug track­ing sys­tems is the iden­ti­fiers.

In sys­tems such as Jira, every time a tick­et is cre­at­ed, an iden­ti­fi­er is as­signed to it. The iden­ti­fi­er is based on a num­ber which in­cre­ments every time. For ex­am­ple, I cre­ate two tick­ets in pro­ject TEC, I may end up with TEC-512 and TEC-513. Those iden­ti­fiers are then used to ref­er­ence the tick­et, both in­side the sys­tem it­self, as well as from oth­er sources, such as ver­sion con­trol com­mit mes­sages.

The prob­lem with those iden­ti­fiers is that they are based on an in­for­ma­tion which is most­ly use­less. Imag­ine I'm work­ing on TEC-512 and TEC-63. What does it tell you? Only that the sec­ond one was cre­at­ed be­fore the first one. How would such in­for­ma­tion be rel­e­vant?

An­oth­er prob­lem—which is most­ly the con­se­quence of the first one—is that it's damn dif­fi­cult to re­mem­ber them. Imag­ine that I'm fix­ing a bug where the data change mes­sages sent to an MQS are not en­cod­ed cor­rect­ly. I may guess that the tick­et called “Change the en­cod­ing to UTF-8 for data change events sent to Rab­bit­MQ,” or I may find it based on the fact that I'm as­signed on this tick­et, or that it was ini­tial­ly cre­at­ed by Robert, or that it was ac­tive yes­ter­day. But if all field ex­cept the iden­ti­fi­er are hid­den from me, I'll nev­er be able to guess that my task cor­re­sponds to TEC-402.

Is there a bet­ter way to ref­er­ence a tick­et?

For in­ter­nal us­age (i.e. cross-ref­er­ences with­in the bug track­ing sys­tem it­self), ti­tles are ide­al. Com­pare:

Ac­cord­ing to the logs, oc­ca­sion­al crash­es are due to the fact that the script is un­able to rec­og­nize the names of the users. Since it hap­pens only for the users with names con­tain­ing char­ac­ters out­side [A-Za-z] range, I sus­pect this to be re­lat­ed to TEC-402. Let's wait for this oth­er task to be solved first, and then Vanes­sa will de­cide what be­hav­ior is ex­pect­ed in a case where the name of the user is not rec­og­nized (for in­stance of the user was re­moved from the sys­tem).

to this:

Ac­cord­ing to the logs, oc­ca­sion­al crash­es are due to the fact that the script is un­able to rec­og­nize the names of the users. Since it hap­pens only for the users with names con­tain­ing char­ac­ters out­side [A-Za-z] range, I sus­pect this to be re­lat­ed to the tick­et “Change the en­cod­ing to UTF-8 for data change events sent to Rab­bit­MQ.” Let's wait for this oth­er task to be solved first, and then Vanes­sa will de­cide what be­hav­ior is ex­pect­ed in a case where the name of the user is not rec­og­nized (for in­stance of the user was re­moved from the sys­tem).

See? In the first case, there is in­for­ma­tion miss­ing, and I have to click on the tick­et iden­ti­fi­er to open the ac­tu­al tick­et in or­der to find what is it about. In the sec­ond case, it's not that I have all the in­for­ma­tion, but some­how I don't need to do an ex­tra click any longer most of the time.

For ex­ter­nal ref­er­ences, things are more dif­fi­cult, and two cas­es should be dis­cussed.

The first sce­nario in­volves a copy-paste. For in­stance, to link the tick­et TEC-402 to a com­mit in a ver­sion con­trol, I can go to a bug track­ing sys­tem, man­u­al­ly copy the iden­ti­fi­er, and then paste it to the com­mand line. In this case, noth­ing pre­vents me from copy-past­ing some­thing dif­fer­ent than the iden­ti­fi­er; for in­stance, a but­ton near the ti­tle of the tick­et may in­vite me to copy it to the clip­board, and then I can paste it to the ter­mi­nal. Ti­tles change, which means that it is need­ed to (1) keep a his­to­ry of all the ti­tles used be­fore, in or­der to be able to find it lat­er; ad­di­tion­al­ly, (2) one needs to han­dle con­flicts: a tick­et shouldn't be able to have the same ti­tle as a pre­vi­ous (and now un­used) ti­tle from the past.

The sec­ond sce­nario in­volves typ­ing. Say I have the bug track­ing sys­tem on a mon­i­tor, and my ter­mi­nal on an­oth­er mon­i­tor. It would be faster to just re­type “TEC-402” in the ter­mi­nal, rather than to switch win­dows and do the copy-paste. How­ev­er, it would even be eas­i­er to al­low me to type the be­gin­ning of the ti­tle of the tick­et. Since “Change the en­cod­ing to UTF-8 for data change events sent to Rab­bit­MQ” is ob­vi­ous­ly too long to type, the only thing which is need­ed to be able to iden­ti­fy it is some­thing which re­moves am­bi­gu­i­ty. For in­stance, “utf8” would be such text if there are no oth­er re­cent tick­ets men­tion­ing UTF-8. Sim­i­lar­ly, “change en­cod­ing” or “rab­bit” might be large­ly enough for the task.

Not only does it make it eas­i­er to ref­er­ence a tick­et for which I know the name, it also makes things eas­i­er when I don't know the ti­tle. If I'm fix­ing a bug where the data change mes­sages sent to an MQS are not en­cod­ed cor­rect­ly, I may type “en­code mqs,” which should be close enough to find the tick­et, al­though it re­quires a bit more smart­ness from the bug track­ing sys­tem, which should know that Rab­bit­MQ is a MQS.

Would it work with a sys­tem con­tain­ing thou­sands of tick­ets? Ab­solute­ly. While it is like­ly that among those thou­sands of tick­ets, a few dozens or even hun­dreds are about Rab­bit­MQ, most will be too old or not as­signed to me. In oth­er words, the sys­tem can start by look­ing at the tick­ets I'm work­ing on. If it finds noth­ing (maybe I for­got to as­sign my­self?), it should take a look at the tick­ets with re­cent ac­tiv­i­ty. If there is still noth­ing (a sit­u­a­tion which would usu­al­ly hap­pen a few times per year), the sys­tem may need some clues from me to iden­ti­fy the tick­et.