Bug Reporting Etiquette

Jamie Zawinski writes "Mozilla.org has a new article on Bugzilla Etiquette. Relevant to more than just Bugzilla, this should be required reading for anyone who wants to file a bug about any product, no matter what bug tracking system is in use. I especially like the mention that "'Open Source' is not the same as 'the developers must do my bidding.'"" Update: 03/19 21:26 GMT by T : If that link doesn't work for you without cutting and pasting, reader Stephen Ostermiller suggests "you might want to use this link which appears to be the same document mirrored elsewhere."

Comments

Inappropriate/Appropriate

[Undaar]

Appropriate bug reporting:
"Upon clicking on Submit in ProgramX release X.X.X the system hangs and generates the following output: ..."

Inappropriate bug reporting:
"Dude! There's a huge f--king cockroach in my kitchen!!!"

article text

[Anonymous Coward]

Bugzilla Etiquette

There's a number of faux pas you can commit when using Bugzilla. At the very least, these will make Mozilla contributors upset at you; if committed enough times they will cause those contributors to demand the disabling of your Bugzilla account. So, ignore this advice at your peril.

That said, Mozilla developers are generally a friendly bunch, and will be towards you as long as you follow these guidelines.
1. Commenting

This is the most important section.

1. No pointless comments. Unless you have something constructive and helpful to say, do not add a comment to a bug. In bugs where there is a heated debate going on, you should be even more inclined not to add a comment. Unless you have something new to contribute, then the bug owner is aware of all the issues, and will make a judgement as to what to do. If you agree the bug should be fixed, vote for it. Additional "I see this too" or "It works for me" comments are unnecessary unless they are on a different platform or a significantly different build.
2. No obligation. "Open Source" is not the same as "the developers must do my bidding." The only person who has any obligation to fix the bugs you want fixed is you. Never act as if you expect someone to fix a bug by a particular date or release. This is merely obnoxious, and is likely to get the bug ignored.
3. No personal abuse. Bugzilla is a window into the world of Mozilla development. The fact that we permit anyone with an account to add a comment does not mean you may harass, harangue or otherwise hassle contributors. Do not make weak threats like "I won't use Mozilla until this bug is fixed!" If a respected project contributor complains about your Bugzilla attitude, then you may have your account disabled. If you don't like this possibility, become a respected project contributor.

2. Changing Fields

1. No messing with other people's bugs. Unless you are the bug assignee, or have some say over the use of their time, never change the Priority or Target Milestone fields. If in doubt, do not change the fields of bugs you do not own - add a comment instead, suggesting the change.
2. No whining about decisions. If a respected project contributor has marked a bug as INVALID, then it is invalid. Someone filing another duplicate of it does not change this. Unless you have further important evidence, do not post a comment arguing that an INVALID or WONTFIX bug should be reopened.

3. Applicability

1. Some of these rules may not apply to you. If they do not, you will know exactly which ones do not, and why they do not apply. If you are not sure, then they definitely all apply to you.

If you see someone not following these rules, the first step is to point this out by private mail. They may well not be aware of this document. Flaming people publically in bugs just causes resentment. In the case of persistent offending you should report the matter to Gerv.

This entire document can be summed up in one sentence: do unto others as you would have them do unto you.

RTFM

[FortKnox]

Amazing. A post to what's basically a "RTFM" to anyone submitting a bug.

Doing this simply creates intimidation. What if some newbie found an integral bug, gets a "RTFM" and is too intimidated to report the bug?
Anyone who has been assailed by "RTFM" in chat rooms can understand where I'm coming from.

Honestly, if open source takes over, the gripe will go from MS to RTFM. Its something that should be addressed now instead of later.

Re:RTFM

[FortKnox]

Being someone that has worked on both sides of the fence, you'd be truely surprised at how a newbie can find crashing and other bugs simply because people haven't thought to do something (because they've been doing it their 'normal' way for so long).

Re:RTFM

[WNight]

Honestly, if open source takes over, the gripe will go from MS to RTFM. Its something that should be addressed now instead of later.

Okay. RTFM.

If you buy Microsoft's software, they're obligated to listen to you bitch about its problems. If you download something I offer for free, I'm not obligated to you in the slightest.

If you can say something both coherent and polite, I'll listen. I do want my software to be better, but I'm not going to be abused by you in the process.

Why do you think people are entitled to anything else? I've very rarely seen people told to RTFM for asking a polite question. They almost always get pointed to docs. If they fail to read those, they get told off, but what else do you expect when you rudely demand someone walk you step by step through something you aren't willing to read a help file for?

It's no different in any other circumstance. Ask for directions in a mall and you'll get pointed to the map. If you ignore the map and ask something it would answer, expect to be ignored. Nobody has respect for whiners who demand that other people solve their problems for them.

One rule that didn't make it...

[japhar81]

Always add bitch at the end of the feature request.

Example
Incorrect
The program could use a print preview feature, please add it.

Correct
The program could use a print preview feature, please add it, bitch.

At least that's rule #1 where I work.

It's not a RTFM though

[xactoguy]

It isn't that at all, though... all they are asking for are some very simple things, things that a newbie would probably do anyway. They are just asking that you don't put pointless comments, that you don't feel that the bug HAS to be fixed, and that you don't abuse or troll in the bug post. Most newbies would probably follow that pretty good on their own already... this is probably more aimed at those who have been around for a little bit, and have posted aimless comments, or have lost sight of the fact that the developers don't have to fix their bug immediately.

Top 10 Bad Bug Reports

[AtariAmarok]

10. My program died. I have stapled an explanation to the install diskette and it is in the mail.

9. I submitted my e-mail address to a dubious web site, and now I get spam. Could you get them to stop? It is your fault: I found the page in your browser.

7. It happened when I hit one of the keys in one of the screens and I saw a message that said something appear. I think it was that version with the 1 in the name. It might have been Mozilla or Opera, don't ask me.

6. Every time I click on the monkey to win $10,000, I never get anything. Could you add a feature in your future version that makes sure that clicks hit the right monkey?

5. The word "Ayatollah" was not spelled right in one of your web pages, www.cnn.com. Please fix immediately.

4. Mothra is attacking!!!!

3. My el33t boxen broke da bugz. 2 u now.

2. Author Stephen King dead at 54

1. My preying mantis is not housebroken, no matter how much I do. What is there to do besides scold him with "Bad bug! Bad bug!"

Bug Reporting Problems,

[PktLoss]

I work for a small company (5 employees), with a user base floating around 1M. And I can't even begin to explain the lost man hours dealing with bad bug reports. I have personally closed over 20 duplicate bugs for a single incident, seeing 3 of the 5 most recently submitted bugs were the same was the first bad sign.

We also deal with the common problem of perception; users think they are doing us the ultimate favour by posting bugs. And as such, feel that any and all means of telling us about them is apropriate, email to 5+ accounts, multiple forum posts, bugtracker, etc. This just wastes time that could have been spent fixing the bug in the first place.

While I would agree that bug reports are helpfull, and nesesary. Condecending tones, foul language, and thinly veiled threats do little.

All i would ask of posters is:
-Replicate it, If you cant make it happen more than once, it doesnt matter (s/w under windows has special quirks of which i am sure you are aware).
-Search It, then /when/ you find the same thing allready there, post a comment with your input, and stats on your OS and machine.
-Include relevant details, killing bug reports under 100chars is really tempting 'it doesnt work', 'the installer breaks', 'its too slow' are all to common.
-Include information on what you were trying to do, and what you were expecting, 'Bugs' are often just a difference of perception between coders, and end users as to what a feature should do.

Here's what I recommend

[azav]

Realize that the developerr has NO idea what is going through your mind, or what you did to make the bug happen.

CLEARLY report the problem like you are explaining it to a 3 year old.

Report your entire platform. OS, vers, ram, vid card, prod vers, etc.

If you take the time to clearly report the bug then you will not waste your time and the developer's time by having to respond to another email asking for more detail.

You SAVE time by being extra clear when you report the issue.

When I was at Macromedia, I determined that a mis reported bug uses 4-6x the manpower than one clearly reported one. This also means that poorly written bugs limit the number of bugs that can be fixed before shipping because of the extra manpower and time used to pass them back and forth.

Good bug:
QA reporter -> Qa manager -> Bug meeting -> Developer -> Bug addressed -> Original reporter -> Bug closed

Bad bug:
QA reporter -> QA manager -> Bug meeting -> Developer -> Bug addressed -> Bug returned to QA -> More info dded, more time spent getting more details -> bug returned to developer -> Bug addressed -> Original reporter -> Bug closed

I know this doesn't look like 6 x the time but when measured, it got up to that high. Especially if a bug has to return more than once.