Bug Tracking System

User's Guide

This guide exists to describe some of the details of the web interface to the BugDB. The interface from the ClearCase side is described in the Wrapper Script Reference, and developers may also want to read the step by step walk-through of the process as described in the Getting Started page.

Objects

Projects

Scope of Projects

Projects are the top level grouping tool for software development efforts. When deciding whether to create a new project or to extend an existing one, the following factors should be considered:

Is there a significant overlap in deliverables? If yes, then don't create a new project.
Are there significant differences in the roles of the participants? If yes, create a new project.

Note that bugs can only belong to one project, and that deliverables (packages) are assumed to exist in only one project.

Project Data Fields

Id, short and long names: Every project has a two letter id. This id is used in various locations. It prefixes every bug id and it is used when applying labels. The long and short names are used in various locations and are free form.
Directory: This is the name of the top level directory where the project's source code is stored. There is currently no validation for this and the field is strictly for information only.
Notification: This contains a valid email address or alias to which new bug reports are sent when they are filed.
ClearCase Server: This is the name of a machine that is running a web server and clearcase with access to the code. This name is used when drilling down to the fixes registered in ClearCase fields in a bug entry.
Default Branch: This is the integration branch that is assigned by default when a bug is assigned to a user.
Status: The project can be in one of two states: Active or Obsolete. A project that is set to be Obsolete will have no users assigned to it and will disappear from most people's project list. A superuser can return a project into the Active state.
Packages: Packages are the deliverables as seen from the customer. Package names may appear as part of a label name, and bugs may be said to have been found in a particular package.
Modules: Modules are chunks of code, usually not visible by the customer. Bugs may be said to exist in a module. This field currently has no other process releavant significance.

Users

A user can have a role in one or more projects. A user who is not a superuser can only see those projects where he has at least a spectator role.

Anybody can create new users, but only a superuser or a manager can assign him a role in a project.

System Users

User names should match those used to log onto the ClearCase systems. User names are used not only to identify people using the BugDB, but also to correlate ownerships of ClearCase objects and to send email.

A crontab script exists to automatically import users into the BugDB as they are made known to the system.

The BugDB supports PAM, NIS and /etc/passwd authentication

User Roles

People can take on different roles in various projects. Roles can be defined on a per project basis, or a user may be assigned a blanket role for all projects.

Spectator: A spectator may look at things, but not modify anything. Everybody who has a role within a project must also have the spectator role.
Submitter: A submitter may submit bugs and comment on existing bugs. A submitter may not assign bugs or change the status of a bug.
Developer: A developer can be assigned bugs to fix, or he may grab bugs, even if they are assigned to someone else. A developer may also rid himself of an assignment, but he may not assign the bug to someone else. A developer may change the status of bugs assigned to him only via the ct-putback wrapper script.
Reviewer: A reviewer can be assigned to review bug fixes. He may also grab unassigned bugs for him to review, or reject an assignment. A reviewer may change the status of bugs assigned to him only via the ct-putback wrapper script.
Tester: A tester may change the status of any bug.
Manager: A manager may modify any bug in any way, may assign bugs to developers and reviewers and may change the roles of any user within the projects managed. A manager may also invite new users into his projects.

A user may also become a superuser. Only a superuser may grant other users superuser priviledges and assign blanket roles for all projects.

User Data Fields

name: The name should correspond to a valid UNIX user name that exists on those ClearCase machines where that user usually operates. Ideally, that name should exist on all ClearCase machines that are operated in concert with the BugDB. Only a superuser may change a user name.
email: This field contains the email address of a user when that email address is different from the default, which could be derived from the user's name. leave this field blank if the user's name, together with the domain name of the ClearCase machines, form a valid email address.
superuser checkbox: Only a superuser can see that checkbox, and may assign or revoke superuser priviledges. It is possible to remove your own superuser priviledges. In that case, the only way to restore them is to hack the MySQL database itself.
password: This field either contains the literal "x" or a password. A user may change his own password at any time, and a superuser may change anyone's password. If the password is the literal "x", then the user will be authenticated via the system's password (PAM, NIS or /etc/passwd), if possible.

Bugs

Bug entries are what this system is about. Bugs must always be assigned to one particular project, although it is possible to link bugs from different projects.

Bug Life Cycle

Most bugs will traverse the following states. Some bugs may turn out to be duplicates of others, and some may turn out to be impossible or too costly to fix, but most bugs will go through their life as shown:

Open: The bug has been submitted, but nothing else happened yet.
Open + Assigned: The bug has been assigned to a developer, or a developer has grabbed the bug and a fix is being attempted. Once the fix is done, the developer runs the ct-putback wrapper script, and the bug enters either the Review state if the review process is used, or goes directly into the Fixed state.
Review: The bug is ready for code review. This state is skipped if code review is not used. The bug then immediatly goes to the Fixed state.
Fixed: A fix of the bug has been registered and put back into the appropriate Integration Branch. Note that one fix may apply to multiple bugs, and that multiple fixesc may be registered for every bug.
Fixed + Labeled: A fix of the bug has built and labeled using the ct-mklabel wrapper script and is awaiting validation by QA. QA may decide to re-open the bug if the fix doesn't conform to the requirements, or may close the bug if no problems are encountered.
Closed: The bug fix has been validated.

Bug Data Fields

Id

The id is a 5 digit number prefixed by the two letter project id. The id is assigned automatically on bug creation and cannot be modified.

Title

This is a headline that appears in all reports, menues and other references to a bug. Attempts should be made to be as concise and descriptive as possible. The title may be changed at any time.

Part (package/Module/OS)

This is a three component field. The first is the package, and should be set to the name of the package of the product where the bug was found. This setting may be used by the ct-mklabel wrapper script to compile a list of fixed bugs that need to be labeled with a label that contains the package name.

The second is the Module where the bug was found or fixed. This is currently not used anywhere, but a future version may use the source tree information in the registered fix to automatically add this info.

The last is the OS on which the product was run and where the bug was detected.

Status

This is the status as described above. In addition to the states mentioned, there are also:

Dup: This bug is a duplicate of some other bug. Mentioning the Bug Id of the duplicate in double quotes (e.g. "ID10243") someplace in the Title or Description will cause a Link to be created between the duplicates.
NoBug: "This is a feature, not a bug."
NotRep: Non-reproducible bug.
Maybe: The decision to classify this bug has been postponed.
OnHold: The decision on whether to address the bug (which has been verified to exists) has been postponed.

Priority

This can be a number between 1 and 4. Besides being able to sort lists by priority, this field has no other effect.

Assigned (branch/developer/reviewer)

This is another three part field. The first part defines the integration branch where the fix should go. Even though it is possible to re-assign the integration branch during the bug's life cycle, it is best to file bugs for one branch at a time. If a bug is to be fixed in multiple integration branches simultaniously and no process exists to automatically migrate bug fixes from one integration branch to the other (e.g. by using ct-bringover -from or ct-redo), then the bug should be cloned.

The second part assigns the bug to a developer. If you assign a developer without assigning an delivery branch, the project's default branch is automatically assigned.

The last part assigns the reviewer. The combination of branch, developer and reviewer is reflected in the naming of the development stream.

Note that only users with the manager role can arbitrarily assign bugs. Only users who have the developer role in the project can be the target of an assignment. Developers can also assign (grab) a bug to themselves.

Type

This is yet another classification and query field. The three possible values are:

Defect: This bug describes a defect, causing the product to behave in unspecified ways.
Enhancement: This entry describes a change in the specification and the fix is the implementation of that change.
Internal: This entry's fix is expected to be a reorganization or some other structural change that doesn't result in any functional changes.

Submitter

This is the author of the bug entry. The author may choose to be notified of any changes. Only the project manager may change this field.

Label (found/fixed)

This two part field contains labels generated via the ct-mklabel wrapper script. The first field should be populated as the bug is filed. It should refer to the label attached to the package containing the product that had the defect. The second field is populated automatically by the ct-mklabel wrapper script and cannot be changed except by re-opening the bug, in which case this field is cleared.

Date

This is the date when the bug was submitted. This cannot be changed.

Problem

This is a large text field that is filled out when the bug is created. Once the bug is created, the contents cannot be changed.

When displaying the content of this field, strings that look like URLs will be transformed into links, and strings that look like references to other bugs will also be displayed as links.

History

This contains the change history and all the comments entered as changes are made. This field cannot be edited, and any new changes are simply appended to the end.

Links

This field contains all the links to and from this bug entry. A link can be created either by cloning the bug or by referencing to other bugs from within the Title, Problem or History fields using a string of the form: XX00001, where XX is the project id and 00001 is the Bug Id.

Attachments

This is a list of files that have been uploaded and attached to this bug entry. Attachments are stored on the ClearCase server and not in the BugDB. This may mean that an attachment cannot be viewed from all locations. Attachments may be limited in size.

Fixes

This is a list of all changes that have been done to the code in an attempt to fix the bug. The only way to add entries here is to actually execute a ct-putback.

User interface

The whole bug tracking system is hierarchically organized as follows:

  bugdb
    |_BugDB configuration
    |_ClearCase configuration
    |
    |_defects (project overview page)
    |   |_project-1 (query frame + one of the results frame below)
    |   |   |_list
    |   |   |_display
    |   |   |_edit
    |   |   |_create
    |   |   |_query
    |   |
    |   |_project-2
    |   |   |
    |   |  ...
    |  ...
    |
    |_projects (project overview page)
    |   |_edit
    |   |_create
    |
    |_users (query frame + one of the results frame below)
        |_list
        |_display
        |_edit
        |_create

Configuring the BugDB

On this screen a superuser may define, edit and remove permissible values for the following objects:

Defect Status
Defect Type
Operating System

Note that changing or deleting any of those values may have far reaching effects and may render the whole system inoperable. Proceed carefully!

Configuring ClearCase Servers and Build Hosts

The ClearCase Server is a designated machine that runs both ClearCase and a web server serving the BugDB pages. There can be as many of these servers as needed, all sharing one database. Projects must be assigned to one such server. This should be the server that has access to all the development work associated with that project.

Every ClearCase server can have its own association between Operating Systems and build hosts. This association will be used by the nightly build crontab scripts to dispatch build jobs. Not all operating systems need to be associated with a build host. Those that don't have a build host will be ignored by the nightly build.

Navigating

The top of every web page is the navigation bar. The upper left usually contains a logo that is also a link to the home page. The upper right will display the path to the current page. Clicking on any element in that path will bring you to an index page that itself has links to all the pages available in that location.

Query Frame

Most pages will have a query frame right underneath the navigation bar. Any change to the fields in the query frame will automatically create a result list below. The bottom left of that frame will contain a set of buttons that can be used to operate on the query result.

Results Frame

The result frame is beneath the query frame, and will usually be populated by executing a query. The result frame will contain one of the following:

Statistics

The statistics page is the page displayed initially upon entering the system from some index page. It will contain relevant data, for example the number of bugs in various states, the number of people assigned to various projects etc.

Most data items are clickable and will execute a canned query to retrieve the records that are relevant to the particular statistical item. For example, clicking on the number of open bugs will list all open bugs.

List Results

The list result is the default query result. It is a one line per item list, shown in groups of 100 items. One can page forward or backwards if a query returns more than 100 items.

Items on the list can be sorted by clicking on the appropriate table header field. Items can be retrieved by clicking on the item's id link in the leftmost column.

Show Results

Whenever a query returns exactly one result, or whenever an item in the query result list has been clicked, the complete record is displayed. Pressing the "Show" button in the query frame will display the compete records of up to 25 items at a time. Just like in the list page, one can page forward or backwards if a query returns more than 25 items.

Certain lengthy data fields may be displayed in a collapsed, abbreviated form. These data fields will have a checkbox next to its headline. Checking that checkbox will expand the contents of that field. Note that this may be slow and may create very big pages.

If the user has an additional role to spectator, an edit button will appear next to the item id on the upper left corner of the item display.

Edit Results

This page looks just like the Show Results page, except that some fields are now editable. The choice of fields and their values depend on the user's role in the relevant project(s).

Pressing the "Submit" button will record any changes into the database and redisplay the item, allowing for further changes. Ever submission that actually changed something will append an entry in the history field of the changed defect.

Pressing the "Clone" button will create a hyperlinked copy of the current bu. Use this if you need to backport a bug to different branches.

If the edit button was pressed in the query frame, the query may return multiple items to be edited. The edit results page will only display one item at a time, but the submit button will have "Submit & Next" inscribed. Pressing that button will submit changes, but will not redisplay the current item, but instead serve up the next item in the query result list for editing.

Create New Instance

New items may be created by pressing the "New" button either in the query frame or in the project overview page. New bugs will have their bug id determined automatically on submit. A new userid or projectid must be defined in this page. It can later be changed only by a superuser.

After submission, the new item will be redisplayed in an Edit Results page and can be further modified there.

Complex Queries

This page has a list of canned complex queries that can be run when needed. It also has a text window where a user can input an SQL query directly. It will usually contain the SQL query set in the query frame, and can be used to debug new queries or to enter highly unusual queries.

Note: It is very easy to enter incorrect queries, and the results may be non-intuitive. It is also possible to hang the database by entering queries that take very long to execute or that use lots of resources (e.g. cartesian joins). Use this feature sparingly. If it turns out that a new canned query is needed, please contact the author.

Reference

The follwing is a list of all database tables and a description of the foreign key relationships. Click on the box representing a database table to get more info on that table.