Issue Tracking Systems

2Modern issue tracking

2.1Issue/Requirement tracking systems

As slightly mentioned in the beginning citation, there is an old saying that any program is never truly finished. There is always something that needs to be added, redone, or fixed. A document containing a call for an adjustment of a system is called a Change request.

2.1.1What should issue tracking systems do?

In such situations, when there are constantly new requirements coming, tools are necessary, which would allow somebody to fully and easily:

• 
  share the information across the team;
  
• 
  have an instant overview of the state of the software;
  
• 
  expertly decide about releasing;
  
• 
  set and update the importance of individual fixes and adjustments; and
  
• 
  have a recorded history of changes.
  

[MIT-BLA] [MIT-HAU1]

This can be compared to old Czech TV series called “Návštěvníci“ (Visitors), where they used a computer called “the Central world brain,” but calling such a tool a brain is not pointless because the main function of such a tool is only “to remember”:

• 
  what should be fixed or created;
  
• 
  what the bug symptoms and appearances are, what actually doesn’t work;
  
• 
  how it should work the right way;
  
• 
  who reported the request, who confirmed, analyzed, implemented the solution, and verified it;
  
• 
  when the request was reported, when it was fixed and when verified;
  
• 
  what led to the decision to choose one way of fixing instead of another;
  
• 
  what changes in code were made; and
  
• 
  how long it took to handle the request.
  

[MIT-AND] [MIT-HAU1] [MIT-KAN]

2.1.2Way of collecting change requests

In the real world, there are various ways how to gather change requests:

• 
  crash reporting tools (BreakPad, Bug Buddy, Dr. Konqi, Windows Error Reporting, …);
  
• 
  issue tracking systems (Bugzilla, JIRA, Rational ClearQuest, Trac, …);
  
• 
  contact forms (web forms, integrated);
  
• 
  discussion boards;
  
• 
  e-mails; and
  
• 
  etc.
  

[MIT-BLA]

As one can see, the so-called issue tracking systems are especially marked because those are tools primarily designed to do this job, to fulfill the above-mentioned requirements. All others are just substitutes, tools primarily designed for different purposes.

2.1.3Benefits of using issue tracking systems

Issue tracking systems, if used in the right way, can bring following benefits:

• 
  Improve the quality of software;
  
• 
  Increase satisfaction of users and customers;
  
• 
  Ensure requests accountability;
  
• 
  Improve communication in the team and also to customers
  
• 
  Increase of productivity of the team; and
  
• 
  Reduce expenses.
  

[MIT-BLA] [MIT-HAU1] [MIT-KAN]

In one of following chapters, the reader will find out more about software development management methods and standards like CMMI and ISO 20000 (which can be also used as a metric of quality of development) – implementing these measures also brings many other benefits.

2.2Change requests

2.2.1Composition of a Change request

A change request is a document containing a call for an adjustment of a system; it is of great importance in the change management process. A change request is declarative, i.e. it states what needs to be accomplished, but leaves out how the change should be carried out. Important elements of a change request are:

• 
  Reporter’s Name or ID. If there are questions, one needs to know who originated the request.
  
• 
  Type of change request states what kind of request it is (bug, enhancement, new requirement, …)
  
• 
  A brief description of what the problem is. For example, “Fatal error when printing landscape.” is a good description; short and to the point.
  
• 
  Build or Version number of the code being built. Is this the shipping version or a build done in-house for testing and development? Some bugs may only occur in the shipping version; if this is the case, the version number is a crucial piece of information.
  
• 
  The component must be specified. This facilitates assigning the bug to a developer assigned to that part of the product.
  
• 
  List details, including how to duplicate the bug and any other relevant data or clues about the bug. Start with how the computer and software is setup. List each and every step (don’t leave any out) to produce the bug. Sometimes, a minor detail can make all the difference in duplicating or not duplicating a bug. For example, using the keyboard versus using the mouse may produce very different results when duplicating a bug.
  
• 
  Severity of the request tells the reader of the bug how bad the problem is. Or in other words, say what the results of the bug are. Here’s a common list for judging the severity of bugs:
  

1. 
   Blocker – blocks development and/or testing work, production could not run;
   
2. 
   Critical – crashes, loss of data, severe memory leak;
   
3. 
   Major – major loss of function;
   
4. 
   Minor – minor loss of function or other problem where easy workaround is present; and
   
5. 
   Trivial – cosmetic problem like misspelled words or misaligned text.
   

Of course, usually a blocker is handled by development team immediately.

• 
  To who is the bug assigned?; who is going to be responsible for the bug and do the work on the bug? Some companies make it so, that there is a set person whose only responsibility is to reassign tickets to the proper person.
  

[MIT-BIR] [MIT-BLA] [MIT-HAU2] [MIT-WIK3]

2.2.2Change request types

Change requests typically originate from one of five sources:

• 
  problem reports that identify bugs, which must be fixed (forms the most common source);
  
• 
  system enhancement requests from users;
  
• 
  events in the development of other systems;
  
• 
  changes in underlying structure and/or standards (e.g. in software development, this could be a new operating system); and
  
• 
  demands from senior management.
  

[MIT-BLA]

Based on the above-mentioned description, one can categorize change requests into the following categories:

• 
  Issue
  Issue can be described as “non-standard” or “not-awaited” behavior of the system. It can be a bug, but needn’t be. This type is usually chosen by people who are not sure how to categorize their problem, and later is usually changed to some other type (bug/enhancement) or closed.
  

• 
  Bug
  A software bug (or just “bug”) is an error, flaw, mistake, failure, fault, or “undocumented feature” in a computer program that prevents it from behaving as intended (e.g., producing an incorrect result). Most bugs arise from mistakes and errors made by people in either a program's source code or its design, and a few are caused by compilers producing incorrect code.
  

• 
  Enhancement
  This category contains requests for improvements or enhancements to an existing feature or task.
  

• 
  Requirement
  Humans usually classify things as requirements when they include new functionality, new features to a system, either determined by ourselves or requested by a customer.
  

• 
  Task
  This is a common category for both functional and non-functional tasks that need to be done. For example, in this category we can put requests for hardware upgrades or other environmental updates, etc.
  

[MIT-ATL] [MIT-BLA] [MIT-HAU2]

Of course, taxonomy of change requests can vary depending on company conventions.

2.2.3Change request workflow

The life of a change request starts as it is opened by somebody. Usually, the submitter of a request does not know (and does not need to know) who the appropriate person for handling the request is, so it is assigned to a lead domain expert. The lead domain expert is the person responsible for assigning requests to the appropriate person in the development team.
After receiving a new request ticket, the first step is verification. A bug verifier duplicates the bug by following the steps listed in the “Details” section of the bug. If the bug is reproduced and has all the proper information, the ticket can be re-assigned to a person who will be responsible for fixing the bug. If the bug is not written clearly, is missing some steps, or cannot be reproduced, it will be sent back to the bug reporter for additional information.
Problems can be also marked as “Fixed Duplicates,” meaning that the problem is specified as the duplicate of the already fixed one.
The developer accepts the request ticket, which indicates that he/she has seen it and is aware that it is his/her responsibility to resolve it. The developer works on the request and based on the conclusions, he/she assigns a status to it, indicating what the next step should be. Actually there are two ways:

1. 
   The problem described is an issue which will not be fixed. The following reasons are possible:
   

• 
  The request is “Postponed,” meaning that because of technical reasons, time constraints, or other factors it will not be incorporated into the code until the next version of the product.
  

• 
  Problem is marked as “Known problem,” indicating that the problem or a similar request is already known, and either a workaround exists for handling it, or it is approximately scheduled some time when the proper fix of the problem can be expected
  

• 
  Issue is “Rejected” by the developer and should be forced to accept (through Council) or closed:
  

• 
  Issue is “Rejected for other reasons” – for example, for the lack of information, change of conditions, impossibility to replicate the issue, etc.
  

• 
  The developer has examined the issue, the product requirements, and the design documents and determined that the bug is not a bug; it is “Working as Designed”. What the product or code is doing is intentional as per the design.
  

• 
  Issue is “Deferred” – meaning that the cost of fixing the bug is too great, given the benefits that it would produce.
  

2. 
   Problem is scheduled by the developer and will be fixed, what can result in following fix states:
   

• 
  Fixed status indicates that a change was made to the code and will be available in the next build. Testers search the database on a regular basis, looking for all “Fixed status” tickets.
  

• 
  Duplicate status, again, indicates that the problem is found as a duplicate of an existing issue.
  

• 
  Resolved means that the problem has been taken care of, but no code has been changed. For example, bugs can be resolved by getting new device drivers or third party software.
  

After being fixed, the bug is reassigned back to the submitter, a representative, or tester, who retests the bug by duplicating the original circumstances. If the bug is fixed and everything now works properly, another test with slightly different circumstances can be performed to confirm the fix. If the bug passes the tests, it gets a Verified status. If the bug does not pass the test, the request is re-opened and is sent back to the developer.

After being tested, the ticket is closed. Here the lifecycle of the change request ends; however, a regression of the problem may occur in the future may occur, and a request can be re-opened and the cycle starts again.
In the diagram below, you can also see the so-called Council. That means the problem is discussed by the representatives of the developers and the testers to make a decision on whether the bug should be accepted or closed.
[MIT-BIR] [MIT-BLA] [MIT-HAU1]

Figure : Request state transition

2.2.4Issue reporting best practices

As soon as you run into a problem in the software, create a new issue request (ticket). In a well-written report, you:

• 
  Explain how to reproduce the problem;
  
• 
  Analyze the error so you can describe it in a minimum number of steps;
  
• 
  Include all the steps;
  
• 
  Make the report easy to understand;
  
• 
  Keep your tone neutral and non-antagonistic;
  
• 
  Keep it simple: one bug per report; and
  
• 
  If a sample test file is essential to reproducing a problem, reference it and attach it.
  

[MIT-AND] [MIT-HAU2]

As was already stated, there are many ways of how a request can end “in the trash” instead of being addressed. To raise the chance of an issue being fixed, there are couple rules which should be followed.

Rule #1 – Write good summary

This one-line description of the problem is the most important part of the report.

• 
  The project manager will use it in when reviewing the list of bugs that have not been fixed.
  
• 
  Executives will read it when reviewing the list of bugs that will not be fixed. They might only spend additional time on bugs with "interesting" summaries.
  
• 
  The ideal summary gives the reader enough information to help decide whether to ask for more information. It should include:
  
  • 
    A brief description that is specific enough that the reader can visualize the failure;
    
  • 
    A brief indication of the limits or dependencies of the bug (how narrow or broad are the circumstances involved in this bug?); and
    
  • 
    Some other indication of the severity (not a rating, but helping the reader envision the consequences of the bug).
    

Rule #2 – Explain how to reproduce the problem

• 
  First, describe the problem. What is the bug? Do not rely on the summary to do this.
  
• 
  Next, go through the steps that you used to recreate this bug.
  
  • 
    Start from a known place (e.g. boot the program);
    
  • 
    Then describe each step until you hit the bug;
    
  • 
    NUMBER THE STEPS. Take it one step at a time.
    
• 
  If anything interesting happens along the way, describe it. (One must give people directions to a bug. Especially in long reports, people need landmarks.)
  
• 
  Describe the erroneous behavior and, if necessary, explain what should have happened. (Why is this a bug? Be clear.)
  
• 
  List the environmental variables (configuration, etc.) that are not covered elsewhere in the bug tracking form.
  
• 
  If the reader may have trouble reproducing the bug (special circumstances are required), be clear about these circumstances.
  
• 
  Keep the description focused:
  
  • 
    The first part of the description should be the shortest step-by-step statement of how to get to the problem.
    
• 
  Add "Notes" after the description, if there are any. Typical notes include:
  
  • 
    Comment that the bug will not show up if step X is executed between step Y and step Z.
    
  • 
    Explain the reasoning for running this test.
    
  • 
    Explain why this is an interesting bug.
    
  • 
    Describe other variations of the bug.
    

Rule #3 – If two failures are visible, write two reports

Combining failures on one report creates problems:

• 
  The summary description is typically vague. Words like "fails" or "doesn't work" are used instead of describing the failure more vividly. This weakens the impact of the summary.
  
• 
  The detailed report is typically lengthened. Bug reports should not read something like the following: “Do this until that happens, in which case do not do this until the first thing is completed and then the test case of the second part must also be complete, and sometimes you may see this, but if not then that….”
  
• 
  Even if the detailed report is rationally organized, it is longer (there are two failures and two sets of conditions, even if they are related) and; therefore, more intimidating.
  
• 
  Often, one bug gets fixed, but not the other.
  
• 
  When reporting related problems on separate reports, it is a courtesy to cross-reference them.
  

Rule #4 – Eliminate unnecessary steps

Sometimes, it is not immediately obvious which steps can be dropped from a long sequence of steps in a bug. Look for critical steps. Sometimes, the first symptoms of an error are subtle.
A list now exists of all the steps that were taken to show the error. Now, the aim is to shorten the list. As each step is executed, any hints of errors must be examined. The following factors should be examined:

• 
  Error messages (i.e. A message appeared 10 minutes ago. The program did not fully recover from the error and the problem evident now is caused by the poor recovery.)
  
• 
  Delays or unexpectedly fast responses.
  
• 
  Display oddities, such as flashes, repainted screens, a cursor that jumps back and forth, multiple cursors, misaligned text, slightly distorted graphics, doubled characters, omitted characters, or display droppings (pixels that are still colored even though the character or graphic that contained them was erased or moved).
  
• 
  Sometimes, the first indicator that the system is working differently is that it sounds a little different than normal.
  
• 
  An in-use light or other indicator shows that a device is in use when nothing is being sent to it (or a light that is off when it should not be).
  
• 
  Debug messages: the debug monitor should be turned on (if it exists on the system) and should be monitored if or when a message is sent to it.
  

If, what seems like a critical step has been encountered, everything else from the bug report should be eliminated. One must now go directly from that step to the last one (or few) that shows the bug. If this does not work, individual steps or small groups of steps can be removed.

Rule #5 – Variations after the main report

The failure may look different under slightly different circumstances. For example:

• 
  The timing changes if additional two sub-tasks are performed before the final reproduction step is hit.
  
• 
  The failure will not show up at all or is much less serious if something else is put at a specific place on the screen
  
• 
  The printer prints different characters (instead of the characters described) if the file is made a few bytes longer
  

This is all useful information for the programmer and it should be included. But to make the report clear:

• 
  It should start with a simple, step-by-step description of the shortest series of steps needed to produce the failure.
  
• 
  The failure must be identified. (Descriptions of how it looks like or what impact it will have.)
  
• 
  A section should be added that states "ADDITIONAL CONDITIONS" that describes, one by one, the additional variations and the effect on the observed failure.
  

[MIT-KAN] [MIT-RAD]

Overcoming objections

Programmers, as humans, operate under time constraints and competing priorities. For example, outside of the 12-hour workday, some programmers are faced with fatigue and apathy, instead of fixing bugs.
Some things will often motivate programmers to fix the bug:

• 
  The situation with the bug is very poor.
  
• 
  The complexity piques the programmer's curiosity.
  
• 
  It affects many people.
  
• 
  Arriving at the fix is trivial.
  
• 
  It has embarrassed the company, or a similar bug embarrassed a competitor.
  
• 
  One of the bug`s cousins embarrassed the company or a competitor.
  
• 
  Management wishes for the bug to be fixed.
  
• 
  The programmer is susceptible to flattery from the person with the requests, trusts the person, owes a favor, or accepts bribes.
  

Programmers avoid spending time on a bug due to the following reasons:

• 
  The programmer cannot replicate the defect.
  
• 
  Strange and complex sets of steps are required to induce the failure.
  
• 
  Not enough information is known and it will take a lot of work to solve them.
  
• 
  The programmer does not understand the report.
  
• 
  The solution is unrealistic (e.g. "corner case").
  
• 
  It will take a lot of work to fix the defect.
  
• 
  A fix will introduce too much risk into the code.
  
• 
  There will be no perceived customer impact.
  
• 
  The fix is unimportant (nobody cares about such a minor error or unused feature).
  
• 
  It is not a bug, it is a feature.
  
• 
  Management does not care about bugs of this type.
  
• 
  The programmer does not like or trust the person with the requests, or the customer who is complaining about the bug.
  

[MIT-KAN] [MIT-HAU2]

This chapter has been written primarily about bugs and their reporting; however, same conditions hold also for other types of requests. When writing request tickets, these conditions should be considered.