Development tools Using bugzilla

We would like to encourage the use of bugzilla for all bugs, issues, queries and problem requests. This makes it much easier to track an issue, make sure that it gets responded to, and hopefully bring it to a satisfactory conclusion for everyone.

In order to help you use the bugzilla system, full information on how to use Bugzilla is available in The Bugzilla Guide: the users manual written by the Bugzilla developers themselves.

Another advantage of using bugzilla like this is that it becomes a useful source of information for other users. Bugzilla can be easily searched to see if a similar question has been asked before, and hopefully already answered.

However, in order for your bug report to be useful to others, including the STLinux support team, it must contain high quality information. It is not very useful simply to tell us that something does not work for you, particularly in situations where we have no access to your code or environment to reproduce it. Please provide precise information concerning your system and setup, what you did, what you expected to happen and what you observed actually happenned. Wherever possible please include actual system output and simple example code demonstrating the problem on one of the ST boards we directly support. Please provide details of any peripheral hardware neccessary to reproduce the behaviour.

Please do not send a 1M line application, written in aggressive C++, for a board we have no access to, which relies upon devices for which you have written the drivers and modified the kernel, and tell us that it crashes after running for several hours consuming undefined inputs. Please.

Writing a good bug report is a difficult task. An excellent essay on the i art of writing good bug reports is available here

We recognise that some users will not want to make their questions public. Much of the work ST does with its customers is covered by NDAs, or maybe simply asking the question would reveal too much to a competitor.

To balance all the above requirements we have configured bugzilla with a number of "products" and "groups" which which have different levels of access.

Terminology

Bugzilla is ideally suited to recording communications between customers and developers, however because its background is for recording bugs, some of its terminology is a little confusing.

In this document we use the term "bug" and "issue" interchangeably, although bugzilla will always use the term bug. A bug in this context is simply a way of collecting the information needed to describe a problem. After all, a particular support request might start out as an issue, and turn into a real bug after further investigation.

Similarly remember that a "product" in bugzilla terms is simply a collection of bugs with some common aspects, and a set of properties, for example visibility and access rights.

Bugzilla products

These are the bugzilla products you might see. Note that because of access controls not all products may be visible to you.

• Public Issues
  Description: Issues tracking for the STLinux Distribution. Bugs in this product will be publicly visible. Any registered user can submit into this product.

  Generally all new issues should be submitted here. This is where queries like "how do I make my mouse work" or "I think I've found a bug in ..." should be submitted. By default this is the only product where people can submit new bugs.

• Company xyz Issues
  Description: Issues tracking for company xyz.

  If you have concerns about making your bug reports public, then on request a special product can be created. This product will then only be visible to members of a special group (usually only employees of your company) and ST employees.

  It should be noted that the problem you are facing is likley to be observed by others, so we would encourage all reports to go into the public catagory and use this catagory for accutely sensitive issues only.

• ST Linux Distribution Bugs
  Description: Acknowledged bugs in the STLinux Distribution.

  These are acknowledged bugs in the STLinux Distribution. As the Linux distribution as a whole is publicly visible, we want to also make the bugs found in it public. Only ST engineers actually working on the STLinux Distribution can submit bugs into this product, although anyone can view them.

• DaveSim
  Description: Fast ST200 functional simulator

  This is completely separate from the STLinux distribution. Anyone can submit and view bugs in this product.

• TestProduct
  Description: This is a test product. Use this to test bugzilla.

  Again this is completely separate from the STLinux distribution. If you want to see what a bug report will look like before submitting it for real, you can log it here. Bugs in this product will be periodically deleted. Anyone can submit and view bugs in this product.

Bug life-cycle

If want to ask a question of the STLinux Distribution developers, how should you do it? Ideally we would like you to create a new bug in the "Public Issues" product. If your want to keep it private however, log it in your private issues tracking product. If you need to keep it private and don't already have one, please send the stlinux support group an email.

If the issue turns out to be a real bug, the STLinux engineers will create a new bug in the "ST Linux Distribution Bugs" product. This will only describe the bug, any customer specific details will be removed. This new bug will "depend on" the origionally submitted bug (and thus the origional bug will be "blocked by" it). Eventually the bug in the "STLinux Distribution Bugs" product will be resolved and the customer who submitted the original issue will be notified automatically.

• Bugs are initially "created" when they are submitted. The initial status is "New"
• Bugs move to the "Assigned" status when the STLinux support team begin to work on the bug. Initial exchanges with the reporter for clarification may occur while the bug is still in the "New" status.
• Bugs will become "Resolved" when a conclusion is reached on their analysis. There a multiple reasons for resolving a bug. It may be corrected "Fixed", recognised as "Invalid", unreproducable "Worksforme", or a duplicate of another bug already in the database "Duplicate". It may be something we decide not to act on "Wontfix", or something we decide to defer to a later point in time "Later".
• Bugs can (and should) bei moved to the "Verified" status by the original reporter when a fix is confirmed as working.
• Bugs move to the "Closed" status when no more work on them is expected. The closed status is often synonymous to "Verified" but is the final destination of bugs for which there is no actual relevant fix for reported verification.
• Finally a bug can be "Reopened" is a previous "Resoluton" proves unsatisfactory and further work is required. Thus a bug can pass though many of these states more than once on its journey to final closure.
• There is also a rarely used status of "Unconfirmed", which can be used for those rumours which can never be properly characterised but which may relate to an issue in the distribution. Reports with this status may be placed in the database to alert others to a possible issue, but are not treated as bugs until more evidence can be elicited.

Creating a Bugzilla account

To use Bugzilla please create an account for yourself, which can be done automatically on line by visiting the web site Bugzilla and clicking on the Open a new Bugzilla account link. All you need to do is enter your e-mail address, which will act as your user name for the system. The account will be created and its password will be mailed to you. You will not be able to log in until you receive the password. You may subsequently change the password on line to one of your own devising, via the User Preferences ("Edit: Prefs") link at the bottom of Bugzilla pages. Optionally you may enter your real name as well and we encourage you to do so.

Full information on the Bugzilla search capabilities are documented in The Bugzilla Guide

When considering reporting a suspected bug or requesting support on a given issue, please search this database first to determine whether the bug has already been reported or relevant advice and information is already present in the database.

When reporting a suspected bug, please enter it into Bugzilla with as full a description of the problem you are experiencing as possible. Wherever possible, give a source code example to enable our support engineers to fully reproduce your problem.

When requesting information, please check first the User Guide, which contain a lot of information which may already answer your question. If you cannot find the information you seek, please provide as precise a description as possible of your needs and describe the context of the question as fully as possible.

By following these simple usage style guidelines the information in the Bugzilla database will be maintained as usefully as possible to other users who may be experiencing similar difficulties or seeking similar information and minimise the chances of the same bug or information being entered into the system more than once.