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. extensions - issues related to extensions to the CZ software. If you don't know whether an issue is related to the core of the software or an extension, use general.
5. general - a catch all. If you don't know what component with which to associate your issue, use general.
6. template - issues related to site specific templates. This should not be used for templates that exist outside the Template: namespace.

The first thing to do when filling out a ticket is select the component to which your issue relates. Then you select the version of the product with which the issue associates. 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 a severity of 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. The first is a summary of the issue. Creating clear summary text for the issue will help others when they search the database for issues they are contemplating adding to Bugzilla. Use keywords in the summary that will help others when they scan it for relevance.

After creating a summary, you must describe the issue in sufficient detail that technical staff can identify and deal with it. If the issue is a bug report, it is necessary that you describe what is the erroneous behavior and how the bug can be reproduced. Technical staff are not magicians, They cannot fix bugs that are not reproducible, so providing sufficient instructions that allows them to reproduce the problem is critical for them to handle it. If the issue you are describing is an enhancement request, you need to describe it in enough detail that technical staff can search for technical solutions. If you know of some potential solutions, describe them.

Sometimes it is useful to provide an attachment to a ticket. This can be done either in the initial submission or later when a follow on comment is created. An example of when an attachment is helpful occurs when a problem relates to page display behavior. Suppose some wiki markup text is not displaying properly, e.g., some TeX markup isn't working as it should. Grabbing a screen shot of the problem and attaching it to the bug ticket helps technical staff to assess what might be the source of the problem. Attachments are also used when a fix to extension or core code is developed. A unified patch can be attached to the ticket to provide technical staff with a solution.

After filling in all the ticket fields and perhaps adding an attachment, the final step is to click the Commit button. This adds the ticket to Bugzilla's database. Obviously, if you don't click this button and close the ticket page window before doing so, nothing is changed in the Bugzilla database and you will have to re-enter the information you supplied. Of course, there are times when you fill out a ticket submission form and then decide to forgo creating the ticket. Simply closing the ticket window without clicking the Commit button achieves this.

Tracking bug reports and enhancement requests

Once you create a ticket, Bugzilla will automatically email you a message each time the ticket changes state. Such events include a change of bug status (e.g,, going from New to Assigned, going from Resolved to Closed), a change to any of the fields in the ticket, including the addition of a new comment, and a change of the technical staff member assigned to the ticket. It is also possible for you to add notifications associated with tickets you did not create. To do this, open the ticket in which you are interested. At the top and to the right is the CC List: field.

Click on the edit link after the CC List: label. This will display a field to which you can add your email address. After doing this, you will receive notifications when the ticket changes.

Sometimes people get tired of all the email they get from Bugzilla. In that case, it is possible to restrict the events that trigger an email. To accomplish this, click on the Preferences link at the top of window, just below the Bugzilla title. Select Email Preferences

In this pane you can tailor which events Bugzilla will use to send you email. If you deselect all of the events, Bugzilla will not send you any email. However, you probably should enable some events, such as "The bug is resolved or reopened".