Title/subject formalism in bug reports (standardising bug naming only): I was <context>, I did <action>, I got <actual behaviour>

Question

Intro

We use different formalisms in titles/subjects for different purposes (story, feature, test), but we have no formalism for bug reports...

We are investigating the advantages of a standardised title format for bugs.

Different formalisms for titles/*subjects* in use, practically

We use with quite a success these formalisms in titles/*subjects* .

Story title

For Scrum stories, we use the following title formalism:

As a <role>, I want <goal/desire> so that <benefit>

Feature title

For FDD (Feature-Driven Development) features, we use the following title formalism:

<action> the <result> <by|for|of|to> a(n) <object>

Tests formalism

For Acceptance Tests (behaviour), we use the following formalism:

GIVEN THAT <conditions>/<initial state>/<context> (no action)
WHEN <actions> (performed by user)
THEN <expected results>/<consequences> (that the system does)

Looking for a bug title formalism

Title/subject formalism

For bug reports, we think we are going to adopt a title formalism close to:

I was <context>, I did <action>, I got <actual behaviour>

I only focus here on the title, not the full description!

Advantages:

• homogeneity across teams (when bugs needs to be passed over)
• strictness for better description and understanding
• mapping of:
  • the bug's 'context' to the acceptance test's 'context'
  • the bug's 'actual behaviour' to the acceptance test's 'expected results'

Disadvantages:

• it is a change to introduce, document, promote, and followup in the project
• you name it

Guidelines for the title/subject

But this formalism is not enough for just a title, as it may need a few guidelines:

• should be as short as possible
• do not mention a technical component or feature, as the guess and confirmation is part of the investigation and not the purpose of the creation of the bug
• do not make any assumption or guess
• just basically describe as briefly as possible the context, action, and actual behaviour, because anyway it will be detailed in the full description
• do not not add any markup like [stuff] or (thing), because it hinders the reading
• do not add any team-specific keywords, as a bug is supposed to be passed from team to team
• do not try to solve the issue at the reporting phase, it is the task of the assignee
• bring the right balance/dichotomy between barely perimetered issue, and fully understood, as in one hand it is too vague, and on the other hand the resolution is almost finished
• stay meaningful

 Full description (not the goal of this post)

Of course, this is not the goal of this post, but in the full description of the bug free text), there will be:

• Context
• Steps to reproduce
• Actual behaviour
• Expected results
• Optionnally
  • links to docs
  • logs
  • diagrams
  • screenshots
  • ...

With all the fields of the bug tracker software, like affected/fix versions, severity, priority, links to other tickets, etc.

But this is not the subject of this post...

Let's get back to the bug titles/*subjects*.

Open questions on bug titles

• Do you think it is worth to put up such a title/*subject* formalism in place?
• How do you name you bugs? (how you fully describe and manage bugs is not the goal of this discussion)

Answer 1

TL;DR

Do you think it is worth to put up such a title formalism in place?

No. A title is rarely a unique identifier across bugs, nor is it likely to communicate enough on its own to justify the constraints.

Titles Should Be Meaningful

While I agree that titles should be meaningful, it is very difficult to create a short formalism that could be summarized in a few dozen characters. For example, you suggest:

I was <context>, I did <action>, I got <actual behaviour>

This is already pretty long, but if you follow this idea to its logical conclusion it should be even longer. Part of a good bug reporting process is identifying how the bug or misfeature failed to meet expectations (sometimes known as the user contract), so the expected behavior is missing. Using your same example, I might say:

I was trying to clear-sign a message
by using the --clearsign flag, but
when I signed the message I got a header and my original text back.
I expected the header and text to be followed by a valid signature block.

The part where I explain what I expected is essential to understanding the issue. Consider: if a press F1 and my team mate gets an electric shock, what exactly is the bug? Is the problem that this should only happen when I press F2? That the electric shock should have been a pie in the face? Or is this actually a feature that's operating as designed?

For the record, I actually filed a real bug report loosely-based on the example I gave above, but the actual title was "GPG Services Signs Improperly with Smartcards." This title might not make sense to you out of context, but was in fact an accurate summary of the bug and took only 46 characters. Using your formalism would have required 139 characters, and (in my opinion) wouldn't have really summarized the issue nearly so well.

The Project Management Perspective

The real underlying issue is why you think that you need to constrain bug titles in the first place. This is often a project smell that indicates:

• Bug reports are ambiguous.
• Root cause analysis is difficult.
• Communicating effectively about bugs within the team is difficult.
• Reporting or communicating about bugs outside the team is difficult.
• Other symptom that probably boils down to communication.

While there's nothing wrong with formalizing your bug-reporting process, keep in mind that process controls should be effectively controlling for a defined problem or risk. In your case, it's unclear what you're controlling for, and whether the proposed control is actually likely to mitigate your risk.

This is something you may wish to discuss with your team and your stakeholders. If it's a genuine issue, it's still usually better to employ a grass-roots solution that has buy-in from the control performers rather than imposing a process by fiat. YMMV.

Answer 2

Well, if such formalism works for you – then I do not want to say anything against.

From my experience:

When the bug is actually missed and not discussed requirement – then I’ll put context and will write it as a requirement and put the actual result. I love to use gherkin for such purpose:

Given I am a user who wants to calculate parking tax
And I’ve set the start date to February 1-st 2012
And the end date is February 29-th 2012
And the current tax per day is $1
When I calculate tax for the period
Then I should get result $29 dollars
But, the actual result was $28

Then I can give a title. The title will include actual component (Tax Calculator) and the issue or assertion:

Tax Calculator should take into consideration leap years
Or
Tax Calculator calculates wrong sum for leap years

On the other hand, I would not put a lot of context if I want to describe server crashes or JavaScript errors. That would be ridicules to describe such things in Given When Then or put some business context for JavaScript error. That is a technical bug and it should have a technical title (such as error message description)
Some my bugs are so complicated to describe and reproduce, so I’ll better attach a video recording.

I am writing bugs for developers and management. My goal is to create a bug reports that will be clear and short. Taking into account the Agile context I am working in – we always can discuss any missed details by Skype of face 2 face.

So, I would write bugs in such formal way. But each project has its own context. And it may work for you if such approach will solve problems.

Answer 3

The only way you can tell if something is a bug is if it does not work as originally intended, that is the original acceptance criteria no longer passes. Simply log the bug with the failing acceptance criteria.

If you did not have the acceptance criteria in the first place, then you either have a lot of technical debt to pay back and this should be deemed as technical debt and made visible to the management.

Finally, if it is a new acceptance criteria that is perceived as a defect, treat it as a change and add it to the product backlog.

Answer 4

One of the new way in a cloud software I heard the following way of testing and bug reporting. This is offshore and onsite model where over lap is 2 to 3 hours.

• User or tester tests the use cases. If it is failing he records entirely the steps followed and then upload into cloud these issue recordings his end of the day.
• Developer when he comes to office check these recordings and fixes the issue.

This way lots of time is saved and issue is clearly defined. Thought of sharing this, might not be accurate answer on the formalism. This is also one way we can do it.