Working with ticketing systems

A detailed overview of ticketing systems, along with some suggested best practises on how we might make best use of them on our projects.

Introduction

Ticketing systems are a software management tool widely used in the software industry, in order to track all of the various tasks that are required to complete a project. Ticketing systems are ofthen called "bug tracking systems", but I think this is inaccurate as these systems are used to track feature requests, or "change requests", as well as bugs.

In my experience, ticketing systems are used in widely diverse ways from one organization to another, or even from one project team to another depending upon the team members and managers working on the project. There does not appear to be any standard best practices for using these systems, so in this article I will try to define some practices that I have found successful over the years, which will cover the usage of ticketing systems in the following main areas:

  1. Tickets.
  2. Milestones.
  3. Estimates.

Tickets

In my opinion, nothing should be actioned without a corresponding ticket. The benefit of taking this approach is that you have a written record of each piece of work that has been carried out on your project, and you have a written backlog of all of the remaining tasks, including (ideally) the priority of each task, an estimate, and a team member that this task is assigned to.

"nothing should be actioned without a corresponding ticket"

Code commits to source control should always reference a ticket by it's number. Again, this allows you to maintain an audit trace of what task has been completed by whom. For example, if I commit a code with the (not ideal) comment "Contains a bug fix for #123", then at least I can look up ticket #123 to get some context around the fix. However if the comment is "Contains a bug fix", then I have no clue other than reviewing the actual code that was committed, which is a much more laborious task.

When reporting a bug, steps to reproduce should be captured. These should be in plain English in the form of a sequence of logical steps required to reproduce the bug, otherwise your development team will have to waste a lot of time trying to reproduce the bug before they can actually fix it.

On resolved tickets the outcomes, including when possible a root cause analysis and a description of the fix applied, should be captured. Closing a ticket with "Fixed" or "Done" is a big mistake, because it gives those that come behind no clue about what was actually done to resolve the ticket, again without having to review the code submitted (assuming those code commits even reference the ticket correctly!).

"The key aim is to make your ticketing system a knowledge repository for your organization"

The key aim is to make your ticketing system a knowledge repository for your organization, therefore the quality and accuracy of the information captured is vital. The clear capture of steps to reproduce, root cause analysis, and outcomes allows your ticketing system to grow into a knowledge base over time. Most modern ticketing systems will contain a search engine allowing you to drill into this knowledge repository, but you can only search accurately based on the accuracy of the data captured.

Milestones

Most ticketing systems, such as those provided by Github and Assembla, provide some support for what are called milestones, but what exactly are milestones, and how can we be using them in our projects?

Historically a milestone was a physical stone marker placed on the side of a path at intervals of miles, which could be used to judge the distanced travelled and therefore the distance remaining on a journey between two points. In software development, a project milestone is typically a desired state that the system will reach at some point in the future, for example the completion of a feature, a move out of beta, or a completion of all features that are on the road map for a given release.

In the SCRUM methodology, project milestones are referred to as sprints, with a software delivery coming at the end of each sprint. Other open ended project milestones are often maintained by teams using the SCRUM methodology, such as a project backlog to contain all of the currently unscheduled tickets, and a triage milestone that acts as an initial gathering point for all bugs before they are "triaged" to determine their priority, who they should be assigned to, or even if they are a bug at all.

Therefore there are basically two types of milestones: deliveries (sprints) versus open ended, and many would argue that open ended isn't really a milestone type at all, but as most ticketing systems force the milestone analogy on us then it make sense for us to track open ended buckets of tickets using these features.

Example milestones

Here are some suggested milestones, based on what I use for the Alpha Framework project hosted on Assembla:

  1. Feature backlog - used to capture all of the feature requests made against your project. This milestone is basically a bucket of unscheduled features. When a feature is scheduled for inclusion in a release, it should be moved out of this milestone and into a sprint.
  2. Bugs - bugs are captured here. Again, tickets here are unscheduled and should be moved out of this milestone once a fix is going to be applied.
  3. Refactors - refactors are improvements that should be made to the system by the engineering team that have been raised inside the team, for example code refactors to ease maintainability or improve performance.
  4. Unit test coverage - this milestone is used to highlight areas of the code where test coverage is weak, in order to suggest new unit tests for subsequent releases.
  5. Sprints (versioned releases) - the real meat of your project, this is where all of the accepted, scheduled, and estimated tasks are kept. There will be several sprint milestones in your project, each representing an actual release (even if it is just an early release to a test environment). Tickets from milestones 1-4 can then be pulled into the sprint milestones, based on the decisions taken during the planning game process used in SCRUM between sprints.

Estimates

Estimates are a black art. In my opinion there is no real science to estimates beyond experience: if you are asked to estimate a task that is similar to one you have done in the past, then you know from experience approximately how long it will take. Equally one task could take two days for one person that would take another, more experienced person one day. It is all based on experience.

"Estimates are a black art."

Estimates are usually tied to customer billing (which is certainly the case in professional services departments), so they usually come under political pressure, often from internal sales and management staff, in addition to the customer who wants to reduce their bill. Do not be surprised in this instance if your initial estimates are challenged, it's common in my experience.

Estimates can be very useful for planning sprints, as they allow an experienced team leader to slot tickets into the release schedule with some degree of certainty that the tasks in question are achievable within the time-frame. This is all driven by feedback from the team in the planning game process, when high-level estimates for each ticket are discussed and decided upon collectively.

If you input your estimates into your ticketing system, it might be able to generate a burn down chart for you. The burn down charts are often printed and reviewed by the team during the daily stand-up meeting (another technique from SCRUM).

Conclusion

As you can see from the topics covered here, there is a lot more science to a ticketing system then simply tracking bugs. Used correctly by a motivated team, a robust ticketing system can really raise the professional standard of your software deliveries, or at the very least highlight where you are falling behind.

John Collins

I have been writing about web technology and software development since 2001. I am the developer of the Alpha Framework for PHP, and the five.today personal productivity app. I love open source, technology, and economics.