2

My question comes from using the agile template in Azure DevOps though its more of a general question about dealing with bug work items.

When a bug work item has been investigated and the issue has been identified, prior to any tasks being created to resolve the bug, where/how is this usually documented?

Looking at the bug work item in the agile template in Azure DevOps the only place would be the discussion field, in GitHub issues this might be captured in a comment. I'm aware the work items can be customised in Azure DevOps should I want to use a specific field for this.

Is comments/discussion the general practice or do other systems have a more formal method of documenting this?

Doc Brown
  • 206,877
mhep
  • 245
  • 2
  • 5
  • 1
    I’m really puzzled by the idea that you’d spend time investigating where in the code the bug resides, and only then create a task to fix it. Just create a task to both investigate and fix the bug. That way the record of the investigation, cause, confirmation through creating a failing test and the fix all gets recorded in one place. – David Arno Nov 07 '18 at 20:20
  • Interested to hear more on your approach. I would ask why you would create a task to "fix it" when on investigation it could turn out to not be a bug. Also a task would be created to detail what task is to be performed and not the outcome. – mhep Nov 07 '18 at 20:31
  • 3
    @mheptinstall: if it turns out not to be a bug, you either modify the type of the ticket, or you close it. One of the goals of the tickets is to track what you're doing at a given time. If you create tickets only after you found a solution, you completely lose this benefit. The issue, then, is that other team members may be doing exactly the same thing, searching for the exact same bug, and be unaware that you're doing it too, leading to lots of wasted time and effort. – Arseni Mourzenko Nov 07 '18 at 20:37

3 Answers3

3

During the investigation

The best place to keep track of progress and any discoveries would be through the comments.

The goal is, after all, to:

  • Make sure you remember yourself what you did yesterday when you continue to work on the bug the next morning,

  • Ensure your colleagues can take over if, for some reason, you should interrupt your work on the bug.

If in the first case, the location doesn't matter, in the second one, bug discussion thread is the natural place where developers would go to get the latest info.

Once the bug is solved

The obvious place to use to document the resolution of a bug would be the commit which solves the bug, and sometimes the commit message.

In most cases, this is all you need for other persons to be able to understand later what caused the bug. If the code is not straightforward and doesn't make the bug cause clear through to a person looking at the diff, chances are you had to either refactor your code to make it more explicit, or add a comment.

One of the reasons is that (1) if the bug existed in the first place and (2) if the difference between the old and the new code doesn't make it clear why the bug existed previously, then there is a risk for someone to reintroduce the bug later.

Sometimes, however, the bug is so weird that no code comments can make it clear. In this case, discussion fields are indeed a good place for those details. The original ticket describes the expected and the observed behavior; the comments explain what happens under the hood.

Examples

Many bug reports on GitHub are a good illustration:

  • The ticket itself describes the problem.
  • The comments explain the discoveries, add the details (edge cases, possible regressions somewhere else when attempting to solve a bug, etc.), and often the resolution itself, before the bug is actually solved. What happens, sometimes, is that someone knows how to resolve a bug, but doesn't necessarily have time to do the actual coding.
  • The revision number of the commit which resolved the issue.
Arseni Mourzenko
  • 135,365
  • 1
    Rather than adding a comment, anywhere, that describes the bug and fix, add an automated test that fails due to the bug, and passes when fixed. That way, if the bug is reintroduced, the test will fail. – David Arno Nov 07 '18 at 20:16
1

Git Hub may be a good place to document and identify the issue, but a better place to document the bug is with a test:

describe('MyMethodWithBug - #123456')
  it('should do something that its not currently doing with this data')
     result = MyMethodWithBug(data)
     assert.that(result).eq.(correctResult)

The test should fail until the bug is fixed. And now you have documented that behavior for yourself and future developers.

Jon Raynor
  • 11,421
  • You should add that this can often be done before the bug is resolved, without this, this does not address the actual question. – Doc Brown Nov 08 '18 at 06:40
1

In the majority of cases I have seen over the past decades, after the root cause of an issue was found the hard work was done. Fixing the bug then could be done often in some minutes or hours, there was actually no necessity to document this in any way before starting to resolve the bug. So when you ask where this is "usually documented", the answer is

  • usually nowhere (in the issue tracking system)

It is often not worth to document the root cause in an issue tracker before the issue is resolved, since this leads to redundant documentation, taking the commit logs of the bug fix and and the in-code documentation as well as the tests into account which are created during the resolvement. If you need traceability, you can also refer to the issue id in those comments.

Even when one needs some notes for "continuing to work on the bug the next morning" (as Arzeni Mourzenko wrote), I don't see any necessity to put those notes into the issue tracker. A piece of paper, or an item in your personal electronic task planner, or a simple text file (all things which can be dumped when the resolvement is done) will be enough. Same holds for information you need to give to other team members when they have to contribute to the resolvement: email, an electronic discussion board, or a disposable "TODO" comment in the code is probably enough for this.

Of course, I have also seen cases where a bug could not be fixed such quickly and the resolvement needed to be split up into several steps (each one worth a ticket on its own). In such cases, the new tickets work as as the documentation you have asked for.

If a bug cannot not be fixed at all without breaking other parts of the software (for example, backwards compatibility), then the ticket will be closed without any further action. This is the only case I can think of where an additional documentation entry in the issue tracking system is required. Most issue trackers I have seen allow to add a "close reason", so put it there.

Doc Brown
  • 206,877