Zikula Network

Get in touch!
irc.oftc.net #zikula
Share your Knowledge!
Follow The Zikulan!
GitHub Core

Show your support for Zikula! Sign up at Github account and watch the Core project!

GitHub Modules


Submitting Bug Report Tickets That Get Results

Submitting bug reports, or "tickets" for Zikula (or any other piece of software) can sometimes be a chore. It is tempting to write a quick ticket that briefly says, for example, "Login is not working", and then let the programmer figure out what's wrong.

Let's remember what the goal of submitting a ticket is, though: get the bug fixed.

The best way to ensure that a bug takes a long time to fix is to give as little information as possible in its ticket. I do a lot of work on the Users module. Seeing a ticket that says nothing more than "Login is not working properly" does not give me any sense of urgency to work on the problem right away. It could be something simple, or something very complex--but I have no idea which from reading the ticket. I do know, however, that I will have to spend a fair amount of time just trying to find the bug before I can even begin to think about a solution. If I don't have a few hours to set aside (which would be a first guess at the amount of time it would take to find the bug, let alone fix it), then I am going to move on to something else that gives me a better idea of what's going on.

To achieve the primary goal of submitting a ticket--getting the bug fixed--the ticket should contain as much information as possible. A feature or function didn't work? How did it fail? Did it give an error message, or did it behave unexpectedly? Did it save when it was supposed to delete? Worse, did it delete when it was supposed to save? How did the user get to the point that the bug happened? What did he click on? What menu choices did he choose? What data did he enter? What version of the software was he using? Was is a beta release? If it happened during installation or upgrade, what instructions for installing or upgrading were followed (and were they really followed)?

Again, the goal in submitting a bug report ticket is to get the bug fixed, so here's how to help that happen faster:

1. Give a short but descriptive summary.

Developers look at the summary in the list of open tickets to decide if they should even bother looking further. If it is not an area of the code they are familiar with, then they will move on. If they cannot even tell what area of the software the ticket relates to, they will move on. If they cannot tell what the general problem is from the summary, they will move on.

Bad: Installs are not working. Better: Installing gives "File Not Found" error. Even better: Clean install - "File Not Found" error after setting admin user name.

2. Describe the bug fully and completely, but don't write the equivalent of a book.

The new ticket template for bugs asks the submitter to "briefly" describe the bug. Note that "briefly" does not mean the same as "in ten words or less". It means be specific and to the point, but include as much detail as is necessary to fully describe the bug.

The submitter is not expected to analyze the code and pinpoint the source of the bug, nor is he expected to provide a solution. (If he can, great! Include it for the developer's consideration. For that matter, if the submitter is going to all that trouble, why not submit a proposed fix as a contributor?)

He is expected to say much more than, for example, "feature XXX is broken". The amount of detail is entirely dependent on the type of bug. If a feature is not working, then how? If the bug is dependent on choices made or data entered, indicate what choices or data caused it. How critical is the bug? Does the system stop working completely? Can the user continue using other features? Is it trivial, like a misspelling or an incorrect color?

3. We need to know how to find the bug.

The steps to reproduce the bug are critical for the developer. Without them he will be hunting for something he likely has not seen before. That could take more time than the programmer can devote to the ticket at the moment, and therefore might delay getting the bug fixed.

For this, a step-by-step set of instructions is usually good. Think of it as a tutorial. Start here. Click that. Enter this data. Wait for the system to return. Choose this menu option. Stand up and walk around your chair three times counter-clockwise. See the error message and there's the bug.

4. What did you expect to see?

Knowing what was expected is half the battle in determining what is wrong. Again, be brief--not a book, but enough for the programmer to know what should have happened. For simple bugs, this might be a single sentence, e.g., "The background color should have been blue." For more complex bugs, this might be a few sentences, a paragraph, or even two paragraphs.

5. What did you really see?

The programmer will compare this to #4 to see how the system failed from the user's perspective. It should be at about the same level of detail as #4.

6. What version or build were you using?

For the current generally available release, a simple version number will do. When testing a new version that has not yet been release, is in beta, or is a release candidate, then the programmer needs more information. Where did the installation come from? Was is retrieved directly from the version control repository? If so, when? Was it completely up to date? Was it retrieved from the build server? What was the build number?

This is important, even though in #7 you'll specify a version number again. Maybe there was a known problem with the builds over a certain period of time.

7. Don't leave the defaults for the rest of the ticket--they are important too!

If the ticket type is not going to be "bug", then this should be changed *before* a description is written. A new template will be put into the description field.

Leave milestone, owner, and cc blank. Keywords are optional, and not really used. Choose an appropriate priority and severity, but if in doubt, leave the defaults. Make sure the correct component is selected--choose the one that most closely describes the area of the bug.

Make sure the correct version number is selected in the version field. If not, the ticket might not show up on the report that developers are looking at. If the ticket is for an installation from the build server, then pick an "X" version, for example "1.3.X SVN".

Finally, not all bugs are created equally. Some bugs are super-simple. They still need a ticket, but they might not need numbers 2, 4, and 5 above to be separate sections. Maybe the bug is a simple spelling mistake. "Registration is spelled incorrectly (Regastrashun) in the title on the pending registration view" is enough for me to know what the bug is, what was expected and what was actually seen. Indeed, for this simple bug, that one sentence even tells me how to find it. The only other thing I need is the version or build number. (Don't delete the template, though. Just fill in the appropriate information for each section, or refer me to something earlier.)

For my first example above ("Login is not working"), though, one sentence will not be nearly enough. The log-in process is complex and has a lot of options. Giving only one or a few sentences might mean the bug never gets fixed, or might even mean that it gets rejected altogether.

If your goal is to get a bug fixed, then spending a few extra minutes writing a good ticket might mean the difference between getting it closed in a few hours or a day, versus waiting days, weeks or months!

Share This | Print


(The URL to TrackBack this entry is: http://blog.zikula.org/index.php?module=TrackBack&id=26,1-71). If your blog does not support Trackbacks you can manually add your trackback by using this form.

You don't have permission to e-mail this story - please login