How to write a helpful bug report

[Tom]

When you are posting to the bugtracker, there are two ways to do it. One is frustrating for us and unlikely to get you the help you want while the other is helpful for us and likely to get you a fix or an answer.

To make a helpful posting, no matter what it is about, always:

   
• use the bugtracker, not the forum, not IRC, not a mail to someone, not the "all realm" channel in-game - use the bugtracker, that is what it's there for and it is the only place we actively monitor for new bug reports. If you don't have and don't want to create a bugtracker account, use "guest" for both login and password.

   
• be as specific as possible - include the page or the action that you are talking about and describe exactly what's going on. Copying the URL from the browser address bar is an excellent way to let us know exactly. Don't assume that we are telepaths and know what you're talking about. Imagine that this is the first time we're hearing about whatever problem you have, including the fact that there is a problem at all.

   
• check if someone else had this problem already, and what the answers were. Getting the same bug report twenty times doesn't make it one bit more urgent to us, it merely uses up time that we could spend actually fixing it. If you have something to add, add it to the existing report instead of creating a new one.

   
• try to duplicate the problem, at least once. Sometimes, things just act up, and it works fine the second time around. And if it's a problem that happens only occasionally, it helps if we know that, because otherwise if we test and it works, we'll discard it.

   
• testing or stable? That is an important difference. If you don't know, look into the URL of the page - it often contains either "testing" or "stable" after the "battlemaster.org" part. If it doesn't, then it's not important. But if it does, then it is important, so let us know.

   
• please be factual and objective - that a bug made you angry and caused your realm some damage doesn't help us in finding it. If you need to express your feelings, do it seperate from the facts. We care, we want you to enjoy the game, but it simply doesn't help when it comes to finding and fixing the issue.

[Charles]

Could you explain what the categories are (Parse, PHP, SLQ, etc)?  I would also like to know how to choose the severity and priority.  The reproducibility is mostly self explanatory for myself, but perhaps you could explain that one too. 

[egamma]

SQL: an example would be the top of the military planner:
Warning: mysql_fetch_assoc() expects parameter 1 to be resource, string given in /var/battlemaster/include/db.inc on line 233

PHP looks somewhat similar, but it will likely have a lot more lines.


You could look at the bugtracker, in those categories, for examples.

[Tom]

I'm actually thinking of replacing those categories with something less technical.

[Anaris]

SQL: an example would be the top of the military planner:
Warning: mysql_fetch_assoc() expects parameter 1 to be resource, string given in /var/battlemaster/include/db.inc on line 233

Nope, that's not a SQL error. That's actually a PHP error. Just because it mentions MySQL doesn't mean it's a SQL error.

Generally, a SQL error will actually give you at least part of a SQL query. These days, it will actually give you a whole bunch of Doctrine stacktrace.

Parse errors are almost always a white screen with a single line on it.

However, generally, the important thing to remember is this:

Don't worry too much about the error type or the severity.

We, as devs, are good enough at categorizing bugs just by looking at them that we generally don't need the metadata.  And, frankly, we don't expect our players to be savvy enough about code to put in the right values.

What we do need is as much information about the bug as you can provide, including (generally) the URL you see it on and the full text of the error, if it's an error message.  And if there's other text on the page, including that is good, too, because it can give us the context of the error (i.e., where it happens in the code).

[Anaris]

I'm actually thinking of replacing those categories with something less technical.

That's probably a good idea, since I, at least, have never seen a need to sort by them, and I have seen lack of understanding of them scare people away from reporting bugs on the bug tracker.

[Foundation]

Here's the recommendation from Joel on Software:

It's pretty easy to remember the rule for a good bug report. Every good bug report needs exactly three things.

• Steps to reproduce
• What you expected to see
• What you saw instead

[/size]

Source: Painless Bug Tracking - http://www.joelonsoftware.com/articles/fog0000000029.html