"Googlebar: Help"

Some helpful tips for reporting a bug

Like any software project, the Googlebar does have, on occasion, features which simply don't work the way they should. Because it can be used on so many platforms in so many different versions of Mozilla, and with many thousands of possible combinations of preferences, the volunteers who develop the Googlebar aren't always able to catch all the errors before every release. If you do find a problem working with the Googlebar, we encourage you to check and see if it's one we've encountered before, or at very least, been told about already.

Besides letting us keep track of existing problems, though, our bug reporting system (which will be explained in a minute) also lets us find out what sorts of features new users want- and, if you have code you think we might like to incorporate, it provides an easy way to get the code to us in the form of "attachments" to the bug (in just the way that you can attach something to email). The interface for our bug reporting system is very powerful, but not always very friendly to new users.

Because of this, and because we always like hearing what users want to see next, this page has been created. The first part provides some tips for using Bugzilla, and the second half provides some guidelines for filing new bugs, to ensure that we have all the information we need to solve your problem.

Tips For Using Bugzilla

The Googlebar project is hosted on the Mozdev.org site, along with many other Mozilla-related development projects. Like the Mozilla web browser itself, Mozdev uses a system of reporting bugs called "Bugzilla", except that our bug database is not hosted on Mozilla.org (because the bug system has the same name in both places, it can be easy for new users to confuse the two!).

As you read the guidelines later on, you'll notice some surprising bits of information that come in handy for resolving problems. The Bugzilla interface is an attempt to keep track of all of them simultaneously, so that until you look closely and take it piece by piece, the interface for filing a new bug can appear pretty confusing. For our purposes, many of the fields (such as what operating system you use, and where the bug is being filed) are pre-filled for you automatically. Currently, the most important fields we like to see filled out are "Severity" (how big a problem is this- small, catastrophic, or just a suggestion to make things better?), "Priority" (Is this something we should hold everything else to get done?), and, of course, "Title" and "Comments", where you tell us what the problem is in detail. If this bug "blocks" other bugs from being fixed, or "depends" on fixing other bugs first, please put the number of those other bugs in the correct one of those two fields, as well.

However, it may be that your problem has already been fixed, or else your suggestion has already been suggested. As a wildly offhand estimate, at least one in five bugs we see reported is a duplicate of one that has been reported before, and so if you do a little legwork before reporting your problem or idea, you'll free up that much more time for our volunteers to work on solving the problem. Part of the difficulty in finding these previously reported problems is, simply enough, that when you visit our "Bugs" page, Mozdev only shows the first ten or so most recently filed bugs, and there are often many more than that. Digging through in detail requires using Bugzilla's rather complicated query system, so to make it easier for new users, we have links to common searches that will be most helpful: by following these links, you can see all the currently open bugs on the project (not just the 10 showed on the main "Bugs" page for the Googlebar project) and read their titles- read carefully, because they may describe your problem in a slightly different way then you're expecting. By clicking on the "all bugs" link, you can go even further back, to see lists of bugs we closed after either fixing them or deciding that they weren't bugs at all; but sometimes an old problem eventually crops up again, and those previous discussions about it can be valuable sources of information, so if your problem seems to be the same as one of them, add a comment and change the status away from "fixed"- this will "re-open" the bug and notify us automatically.

Guidelines for reporting a bug

If you read the last paragraph of the previous section, you've already learned how important checking our bug list can be before filing a bug, as well as some tips for how to do so. This can't be understated- checking our list of old bugs in detail can save us a lot of time that can be devoted to fixing the problem, not just naming it a duplicate of a dozen other bugs!

However, while important, it's not the only thing you can do to make our jobs easier. Some bugs have already been fixed between one release and the next, and so we make available our "Experimental" releases, chock full of new changes and new things to see and do. When reporting a bug, please try the Experimental release first- the problem may have been fixed!

If the bug hasn't been fixed, and you file your own, some general bits of advice will apply: first, make your title clear. "That thing don't work none, dude" and "I hate you all" are examples of titles that don't help us one bit, while "After upgrading, the default search comes up in Spanish" gives us a real idea what the bug is about when we're skimming through those long lists of problems vying for our attention. Also, read the above section on bugzilla to find out what fields we'd like to see filled out, as doing our legwork and filing really informative bug reports is the most helpful thing you can do short of fixing the bug yourself and telling us how. What information we need depends on what kind of problem you're reporting. Logically enough, most of the bugs reported for the Googlebar can be split up into three categories for our purposes: Problems with the interface, problems with the functionality, and Suggestions for improvement (yes, suggestions are counted as bugs. We didn't name it that way, but we're stuck with it!). Before discussing the special categories of bugs, and the most important information to include for each, there are a few extra bits of information not tracked by the Bugzilla system that we'd like to ask you for.

First, things change between versions of Mozilla, and there are some differences between Mozilla and Firefox. Because of this, make sure to tell us not only which browser you're using, but also the version number. Also, things change between versions of the Googlebar: make sure, when filing a bug, that you tell us whether you've installed it before (do you see the problem only when upgrading?), and what version you have installed- this number can be gotten from the Googlebar preferences panel (select "Toolbar options..." from the drop-down menu on the left side of the Googlebar).

Third, some problems are caused by confusion between the Googlebar and another extension or part of Mozilla. This is rare, but when one particular feature flat out refuses to work or makes another extension look funny, it may be a case of this conflict causing confusion in the browser: it very literally thinks it has two left feet, and as a result, neither foot will work! So, be sure to tell us what other extensions are installed if you think this may be the case.

Now, for the special categories:
Interface problems are, as it sounds, problems with how the Googlebar LOOKS. If it's too tall, too short, or some parts of it flat out don't appear, that's an interface bug. These can also be problems with figuring out how to make the Googlebar work- is it too cluttered? Too confusing? For problems like this, one important extra bit of information is to tell us what THEME you are using, because the Googlebar looks different in different themes. We try the toolbar in the most comon themes, but if we can't figure out what you're using, we won't be able reproduce the bug and figure out how to fix it. Also, describe exactly where the area of the problem is, and anything else you did prior to when the Googlebar started looking strange- sometimes small visual problems can escape our attention, so we need your help to find them.
Functionality issues are slightly different. Aptly named, these are problems where something flat-out doesn't work. Did we break something in Mozilla? Did we just never make something of our own work right? Make sure you describe exactly how you arrived at the problem: do you have any special settings? What other extensions are installed? If your problem was installing the Googlebar, did you get any "error codes"? (Tell us the number!) Some features only stop working on certain kinds of web pages, so if that's the case, give us the address of the page and let us try it out, too; other features never work, in which case going to "Tools- JavaScript console" and pasting in the text of any Googlebar-related error messages you get might give us a clue. And if you think the problem is with how the feature works more fundamentally- well, how should it work?
Suggestions filed in bugs can provide some new ideas, but only if you give us a clear description of what you want to see. How should it work? How should it look? Is there another project or article somewhere that we could look at to try the idea out and see what you mean?

When reporting any bug, be sure to use your common sense when deciding what kinds of information to tell us- don't go overboard, but anything that might be related to how to reproduce your problem will give us a clue to how to fix it, and doing your homework in advance can make the process much easier for everyone all around, as well as saving us days of playing email tag to track down more information from you. To summarize:

Always tell us... Interface problems Functionality problems Suggestions
  • Browser name and version
  • Other extensions installed? (if relevant)
  • Googlebar version number
  • ...Have you installed us before?
  • Theme name and version
  • Steps to reproduce
  • Always visible, or sometimes?
  • Install error? (Give error code)
  • Specific to one web page? (Give address)
  • Text of relevant errors on JavaScript Console
  • How should it work?
  • How should it work? Details!
  • How should it look?
  • Examples of other programs that do this

Again, we thank you for reporting bugs and idea- follow these guidelines, and we'll do our best to resolve your problems as soon as possible while we work to make the Googlebar better. We can't guarantee we'll implement every suggestion, but because we have such an open development process, we will definitely give you a fair chance and give you some pointers about what to do if you still want to see an idea implemented that's outside what we normally do. Ready?
Start reporting your bug!