109311 - Bugzilla Users' Best Practices Guide

Status: RESOLVED FIXED

(Bugzilla :: Documentation, enhancement, P3)

Description

[Matthew Tuck [:CodeMachine]]

We need to let users know how they should be using Bugzilla.  This document
should not be a part of the Bugzilla Guide, it should be linked from the
Bugzilla pages.  It should be templatised so it can be easily customised by
installations and bmo can add their own Mozilla-specific stuff.

To demonstrate what I mean, the following comes to mind:

1. Don't use sigs in comments.  Everyone knows who you are.
2. Don't add comments saying what you're doing, as they cause people to receive
e-mail who aren't interested.  Only comment if you have something to say about
_why_ you're doing something.
3. If you need to link multiple bugs to one bug via dependencies, edit the one
bug rather than the many so as to reduce bugmail sent out on the one bug.

Let's try to keep this non-controversial (ie no "take XXX discussions to
newsgroups").

Asa can you please CC any people who might have something to say here.

Comment 1

[David Lawrence [:dkl]]

Also add, please no debugging output, logfile output, or other large amounts of
cut and pasted text to be put into a comment that could more appropriately be
uploaded as an attachment. Small snippets of output that show individual errors
or offending lines are fine.

Comment 2

[Christian Reis]

This is an excellent idea. Perhaps have a short explanation of the "Bugzilla
process" that is used in many bugzilla sites (triage, peer review, status and
resolutions) also MattyT?

Comment 3

[Gilles Durys]

An useful addition would be : reporters do not need to add there mail address in
the cc list (I often see that one)

Comment 4

[Matthew Tuck [:CodeMachine]]

Some people add themselves to CC so they can not receive mail for most of the
bugs they've reported, are assigned to etc.  If we could do this we would fix it
in Bugzilla.  Maybe if and when we have personal keywords we can use them for
filtering instead.  The reporter abandonment proposal would go part way (bug
#94247).

Comment 5

[Dave Miller [:justdave]]

The docs should always be up-to-date when we release.  Forgot to exclude
Documentation when I mass-retargetted.

Comment 6

[Matthew Tuck [:CodeMachine]]

Large amounts of subsidiary information (test cases, sample outputs, patches,
etc), should be added as attachments rather than a part of comments.

Comment 7

[Asa Dotzler [:asa]]

a few more suggestions for guide:

*trim screenshots. no need to show the whole screen if you're pointing out a
problem with a single button, piece of text,icon, etc. 

*you do not need to comment when adding or removing an email from the cc: list. 

*you do not need to put "any url" or similar strings in the URL field. 

*please type "bug" before bug numbers so that they get linkified by bugzilla. 

Comment 8

[Blake Ross]

Cc'ing timeless, he'll need to reconcile this with his own guide, which he often
breaks.

Comment 9

[Hixie (not reading bugmail)]

* don't attach simple test cases (e.g. one html file and one css file and one
image) as a ZIP file. Instead, upload them in reverse order and edit the
referring file so that they point to the attached files.

Comment 10

[sairuh (rarely reading bugmail)]

methinks there should to be a link to
http://mozilla.org/quality/browser/navigator-who2bug.html --whose aim is to more
quickly direct browser bugs to the appropriate developers and qa.

Comment 11

[Matthew Tuck [:CodeMachine]]

Try to make sure that everything said in the summary is also said in the first
comment.  Summaries are often updated and this will ensure your original
information is easily accessible.

Comment 12

[Asa Dotzler [:asa]]

Don't press stop in the browser or surf to another webpage until the changes
have all been submitted for your bug (process_bug.cgi is finished loading). If
you do, all of the changes won't be completed. (Is this a bug?) 

Comment 13

[Dave Miller [:justdave]]

yes. That's a bug. Bug 104589 specifically.

Comment 14

[Matthew Tuck [:CodeMachine]]

As well as talking about "bug" for linkifying, talk about the "comment" syntax
too.

Comment 15

[Christopher Aillon (sabbatical, not receiving bugmail)]

1. Do not HTML escape HTML source.
   <HTML>
   <HEAD><TITLE>This is annoying...</TITLE></HEAD>
   <BODY>

2.     There is no need for indenting text like this.
       White    space    will    be    preserved.

3. Speaking of the bug 1234 syntax, it is a tad annoying to read "See bug 12345
   in Bugscape for more info."  I realize that nscp has its own Bugzilla 
   install, but it is annoying to have bug 12345 linked to the b.m.o bug 12345.
   Direct links to Bugscape would work better.  Not only would it make it less
   annoying for Joe MozillaUser, but also for NSCP people who can then just
   click on a link directly to the bug instead of having to manually go to
   bugscape and type in the bug number.  If anyone refers to bugzilla.redhat.com
   or bugzilla.gnome.org or any other bugzilla install, I expect the same thing.

Comment 16

[Matthew Tuck [:CodeMachine]]

We might want to incorporate the bug writing guidelines into this document.

Also, its usually a good idea to separate large patches into small patches if
feasible, because they are easier to review and can be checked in separately.

Comment 17

[Christopher Aillon (sabbatical, not receiving bugmail)]

If you feel your bug was duped incorrectly, please question it in your bug, not
the bug it was duped to.  Feel free to CC the person who duped it if they are
not already on the bug.

If you feel your bug was otherwise resolved incorrectly, please feel to re-open
it and address any issues that were raised in the bug (missing information/steps
to reproduce, need to try on a recent, as opposed to 5 month old build, etc). 
Always download the latest build and attempt to reproduce before re-opening a bug.

Comment 18

[Dave Miller [:justdave]]

Barnboy changed his email address and opened a new account instead of having the
address changed on his existing one.  Reassigning all docs bugs to his new account.

Comment 19

[Gervase Markham [:gerv]]

OK, most of this has gone into the Hints and Tips section of Using Bugzilla in
the Bugzilla Guide. Please file further bugs if you have more ideas.

Gerv

Comment 20

[Matthew Tuck [:CodeMachine]]

The Bugzilla Guide is not the appropriate place for this.  This is user
documentation and it should be a part of online help.

Comment 21

[Gervase Markham [:gerv]]

The Bugzilla Guide is a guide for all Bugzilla users and admins - it now
specifically has a user manual section. So that's alright.

Gerv

Comment 22

[Matthew Tuck [:CodeMachine]]

We significantly shortchange our users by doing this.  Admin and user
documentation are two different things and should be treated as such.

In particular, user documentation should be administrator customisable, and be
able to customise itself to the installation settings.  This implies it should
be templates, and not a part of the Bugzilla Guide.

Comment 23

[Gervase Markham [:gerv]]

OK, I'll buy that. So you are saying that all the user documentation should be
customisable page.cgi pages (see bug 170213)?

Gerv