User:Dan Nessett/Sandboxes/Sandbox 2

There are two ways to report a bug or submit an enhancement request in CZ. The first is to send an email to cz-bugs@citizendium.org. This option is best if you do not understand the underlying technology that implements CZ's wiki or the forum threads. For instructions how to submit emails to this list see CZ:Buglist.

The other way to accomplish the same objective is to use CZ's Bugzilla issue tracking software. This requires a bit more effort, but in the end it allows you to stay apprised of the status of the report/request as it makes its way through the investigation stage to resolution. If you have even only a modest understanding how CZ's technology works, this is the recommended approach. These instructions explain how to use Bugzilla and also describe some of the features it provides to help you track your report/request.

Registering on Bugzilla

In order to use Bugzilla, you must first register (if you chose not to register, you still may view its reports/requests. See searching Bugzilla's database). In order to register, you must provide an email address where report/request status messages are sent as the report/request evolves. Note that this email address is visible to anyone who is registered on Bugzilla, although unregistered visitors cannot see it. So, if you wish to protect your normal email account from access by registered users, you might consider creating an email account on Yahoo or Google for this purpose.

Your account on Bugzilla is associated with your email address. In keeping with CZ's policy of using real names, you must supply both an email address that is clearly associated with your name and you must also supply your real name (the one you use on CZ) when registering. If you do not do this, a Bugzilla administrator will delete your account and ask you to reregister using the appropriate information. To register, use the following link CZ bugzilla. When the page is displayed, you will notice three large buttons (the following image is cropped). Once you are registered and log in (see below), you can click on the Preferences link in the row just below the Bugzilla title and select name and password. In this preference pane is a field in which you should fill in your real name. Once you have done that, click Submit Changes to save the contents of this field.

Click on the large blue button (Open a New Account). A new page will appear with a text box labeled Email address. Enter your email address in this field and click the send button below the field. Bugzilla will then send you an email message at this address with a link you must access within the specified amount of time. When you click on this link, you will confirm your account. You can then go back to the main Bugzilla page CZ bugzilla and complete your registration.

Using Bugzilla

Once you are registered, you may file bugs and enhancement requests. However, you must first login.

Logging into Bugzilla

Click on the Log In link, which will change the link to an area with two fields, one for your username and one for your password. Your username is the email address you used to register and the password is the one you selected during registration. If you have forgotten your password, click on the Forgot password link and enter your email address in the login field. An email will then be sent to you instructing you how to reset you password.

Searching Bugzilla's database

Before filing a bug report or enhancement request, you should search the Bugzilla database to ensure someone else has not already filled an identical report/request. To do this, click on the large button labeled Search. This will display a search page.

You can search Bugzilla's ticket database whether you are registered or not. To do conduct a search follow the instructions given above to display the search page. If you change Status: and Product: to all, the search will return a list of all tickets in the Bugzilla database. Generally, this displays more information than is interesting. So, it is best to restrict your search. For example, if you are interested in seeing a list of all open bugs filed against the Forum software (of which CZ only holds those related to configuration on its platform), change Status: to open and Product: to Forum.

CZ Bugzilla classifies issues by one of three catagories:

1. CZ - this corresponds to issues associated with the wiki itself.
2. Forum - this corresponds to issues associated with the Forum software.
3. Infrastructure - this corresponds to issues associated with the underlying functionality that supports both the wiki and the forum software. Generally this category is used only by technical staff. Non-technical-staff do not normally use this category when reporting a bug or making an enhancement request. If you believe there is an issue that you need to report in regards to CZ's infrastructure, contact one of the technical staff about your issue. (see, Other CZ groups)

To search for a bug report or enhancement request related to one you wish to create, change Status: to all and Product: to the appropriate category. Then enter some keywords associated with your issue into the field labeled Words: and click on the button labeled Search.

A list of bugs will be returned corresponding to those keywords. If there are only a few tickets shown in the list, click on the button labled Long format. This is a quick way to see all of the comments associated with each ticket. If the list is longer than around 10, you probably want to look at the Summary field of each and only examine those that seem relevant to your issue. To inspect a particular bug in the list, click on the ID of the ticket in the first column. This will display the full ticket information. Whether you use the Long format option or look at tickets individually, you should read through the comments associated with each ticket to see if one already exists for your issue.

Filing a bug report or enhancement request

If your search did not reveal an existing ticket that corresponds to your issue, you should then file a new one. To do this, return to the main page (if you are not there already) and click on the green File a Bug button. This displays a page for entering ticket information.

]

Click on CZ:, if your issue is related to the CZ wiki or on Forum: if it is related to the CZ's Forum software. After selecting the appropriate category, a reporting page is displayed (the image below blacks out the user name for privacy purposes).

If you have selected Forum:, the ticket form displays only one Component:, configuration. Since CZ only uses the Forum software, the only problems it deals with are CZ specific configuration issues. However, if you selected CZ:, there are 6 components from which to select (you must select one).

1. configuration - issues that relate to the configuration of the wiki software.
2. core - issues that relate to the coding of the wiki software.
3. database - issues related to the backend database that stores the wiki software data (pages, histories, etc.). Generally, only technical staff will select this component.
4. general - a catch all. If you don't know what component with which to associated your issue, use this one.
5. template - issues related to site specific templates. This should not be used for templates that exist outside the Template: namespace.

The first thing you do when filling out a ticket is select the component to which your issue relates. Then you select the version of the product to which the issue relates. As of 11-02-2009 there is only one version, which is preselected. As with most fields, you should not be too concerned about getting these selections exactly right. It is normal for technical staff to clean up ticket submissions with the correct information.

To continue filling out the ticket, you select an issue severity, a hardware platform and an operating system (OS). If the issue is an enhancement request, select enhancement. Otherwise, select one of the following:

1. Blocker Blocks development and/or testing work.
2. Critical crashes, loss of data, severe memory leak.
3. Major major loss of function.
4. Normal regular issue, some loss of functionality under specific circumstances.
5. Minor minor loss of function, or other problem where easy workaround is present.
6. Trivial cosmetic problem like misspelled words or misaligned text.

As stated above, don't worry too much about selecting the correct value. Just make your best guess. If it is wrong, technical staff will correct it.

The next thing you need to do is select the hardware and software platforms. If the issue relates to the CZ servers, you should select Hardware: PC and OS: Linux. Otherwise, you should select the platforms that you think are right. For example, if the problem only shows up in Safari running on Mac OS X, then select Hardware: Macintosh OS: Mac OS. If the issue is a problem or an enhancement that is only relevant to Microsoft Windows, select Hardware: PC OS: Windows.

While the selections you make of the previous fields are not absolutely critical (but try to get them as correct as possible), the next two fields are. Specifically, you must describe the issue in sufficient detail that technical staff can identify and deal with it.