Create a trail ...

13 September 2016

Whilst most projects are quite different from one another, the project management tools used are usually very similar. For example, most projects (hopefully!) store the source code in some form of source control system, like Git. Also, most projects involve some form of bug tracking system - eg. JIRA, Mantis, Redmine, etc.

Quite often, there's a direct correlation between an item in the bug tracking system, and a change that is checked into source control. The bug tracking system normally contains a combination of features and bugs, and may be used from the very beginning of the project.

Given this correlation, it makes sense to reference one from the other for future reference. A ticket in the bug tracking system always contains a description and comments; and source control always involves commit messages describing each atomic change that is made.

Having worked in the past for companies that enforce strict standards around commit messages, it feels natural and automatic for me to reference a ticket number inside a commit message, and vice versa. And depending on your chosen source control and ticket management system, you may well have tooling to help you with this, providing hyperlinks, etc.

Unfortunately, I do quite often see commit messages that are directly related to a particular ticket, but with absolutely no reference to which one. This makes it REALLY hard to track down exactly what change was made for a particular issue. Especially when the commit messages are also really obscure - eg. Fixed bug in order management system. This would have been just as easy to write [#1234] Fixed bug due to misspelt property in model. That way the commit message gives a brief summary, but you can quickly reference the ticket for more details. I normally would also include the commit ID in the closing comment of the ticket tracking system, so there's a two-way reference.

I know it's tempting to skip this kind of thing when you're in a rush, but it really does take seconds, and can save quite a bit of time if you need to back reference that change in the future.