Composing effective issues

Effective issue reports assist in the process of refining projects and reaching the ultimate goal of completion. A useful issue report normally has two qualities:

  1. Reproducible. Issues that cannot be duplicated are generally marked invalid. Provide detailed instructions for duplicating your issue.
  2. Specific The more details you provide the easier it is for the engineer to identify the problem and solution.

For example: you're testing a web browser. You crash at example.com, and want to write up an issue report:

Inappropriate:

"My browser crashed. I think I was on example.com. My computer uses Windows. I think that this is a really bad problem and you should fix it now. By the way, I don't like the icons. Nobody will use your software if you keep those ugly icons. Oh, and my grandmother's home page does not look right, either, it's all messed up. Good luck."

More appropriate:

"I crashed each time when I went to example.com, using the 10.28.99 build on a Win NT 4.0 (Service Pack 5) system. I also rebooted into Linux, and reproduced this problem using the 10.28.99 Linux build.

It again crashed each time upon drawing the banner at the top of the page. I broke apart the page, and discovered that the following image link will crash the application reproducibly, unless you remove the "border=0" attribute:

<IMG SRC="http://example.com/images/topics/topicfoos.gif" width=34 height=44 border=0 alt="News">

Entering an issue

Because of it's highly customizable nature, entering issues in Scarab can be as individual as the person entering the issue. There are some basic principles that apply to all issues being entered in the database: for each issue entered you will define the issue and add supporting information. You may also be able to check the database for duplicates.

Defining issues

Each issue type has a unique set of attributes specific to the needs of the issue type. When entering the issue you will want to add values for as many attributes as possible. Remember, when creating effective issues you want to be as specific and detailed as possible. Attributes allow you to add meaningful information that can be easily used for tracking and searching purposes.

While creating the issue, use the textual fields to add as much specific information for the issue. Your administrator may have defined attributes to track specific generic information, but the more details you can add into the text fields the better issue you will have created.

Adding supporting information

In the issue entry process you can add additional relevant information; you can include dependencies on other issues as well as attaching appropriate files (like patches, emails, etc.).

Setting dependencies: Issues often have dependencies on other issues. One issue may require a resolution from another before any work can be done. Two issues may have parallel resolutions and need to be tracked together, though they have no direct influence on one another.

There are three levels of dependencies within Scarab: blocking, duplicating and non-blocking. Blocking issues prevent the issue being blocked, from being resolved. The blocking issue must be addressed before the blocked issue can be resolved.

Sometimes duplicate issues may be entered and need to be tracked separately. Marking an issue as a duplicate allows users to track efforts on both issues. Duplicates may be in different modules or the same module.

Marking issues as non-blocking dependencies also allows users to simultaneously track efforts on two or more issues.

You can track the progress of interrelated issues by using the Dependencies section of the issue and clicking on either the issue ID or the Issue summary links to the issues. In this area you can also redefine the Dependency type.

Issue attachments: Keeping track of information relating to an issue is simplified using the issue attachment feature. You can include email conversations, relevant documentation, patch files, or any other supporting file. If you need to include a url, you can add that into any text field. To add a file, use the Add attachment section in the Enter new issue form (if you have duplication active, this will appear after the duplication checking process). To do so, enter a brief description of the attachment and use the browse button to navigate to the file on your local system or enter a path for the file and click the Add file button. You can repeat this process to add multiple files.

Handling Duplicates

If you have duplication checking active, Scarab will use a subset of attributes to check for possible duplicates in the database. If duplicates are found a report of similar issues will be presented with your issue listed at the top. Review the issues listed to determine if an existing issue covers the issue you are entering. You can do a number of things at this point:

Reviewing duplicates

For each item in the database that has been identified as a possible duplicate for the criteria you entered, an entry appears in the Identified as duplicate screen. You can change the sort order by clicking on the title of the column. Each column represents an attribute used in the search for duplicates.

Each module has a set of assigned attributes. The values entered for each of the attributes is parsed into a search string so that each value becomes a searchable string. Use this page to compare your potential new issue with those in the database.

Commenting on like issues

The note box under the list of like issues allows you to add comments to issues without going to the issue. You may want to comment that you are experiencing similar problems, recommend a solution for a similar issue or add to the information in an attribute. Information entered in the Notes box will be added to the Notes section in the issue. To add comments, enter text in the Notes box and click the Submit button. Once your entry has been processed a message will appear at the top of the screen letting you know that your comment has been added.