Basic Rules

..for using the Issue Tracker

Why you should read this

Imagine how many people later on will read your issue (means the issue which you submitted, or which you participated in)

You see, there are a lot of  people who may read what you wrote. Thus, the majority of the rules below focuses on making reading easier: Though they sometimes take you some little time to follow, they often save others a lot of time later on.

So please, not only when you submit new issues, but also when you add comments to existing issues, try to help others by obeying these simple rules.
Since not obeying them makes defect handling more difficult (sometimes much more difficult), people may tend to not deal with your issues until they are in a shape to reasonably do so.

The rules

For those of you who like it short and simple:

One problem - One issue

When you report a problem, please submit one issue per problem. There are various reasons for this, amongst them:

In particular, if you're going to write sentences like "Besides this, I noticed that ...." or "There are several problems with....", then please seriously ask yourself whether you should submit multiple issues instead of a single one.
If you don't follow this rule, be prepared for people asking you to split up your issue.

Provide a meaningful summary

A lot of people have to deal with a high number of issues on a regular basis. Usually, this happens with generating reports about issues, where the summary of all issues, plus some additional data, is displayed. Thus, the summary of an issue is of very high importance: If properly chosen, it allows to

Thus, please avoid summaries like "Big Bug in OpenOffice.org" or "Impress problem" - they are of no real help, and force people to waste time to actually browse to the issue (instead of seeing it in a report) to see what it is about.

Provide step-by-step descriptions

You, as the submitter of a problem, know exactly what you were doing when you were hit by the problem. However, most other people probably don't. For instance, they may have a completely different workflow for doing the same things you are doing.

Even an phrasing as innocent as "format the text as bold" bears the potential for a misunderstanding: You can get a bold text by assigning a style to it, by selecting it and pressing the respective button in the toolbox, by choosing "Style|Bold" from the context menu, by choosing "Format|Character" from the menu or "Character" from the context menu and then doing the change in the dialog. Thus, a problem description such as "When I try to format the text as bold OpenOffice.org crashes" is of nearly no use, since it forces other people to ask back what you meant.

This may be a trivial example, and you could argue that other people can simply try, and then they will eventually encounter the problem and thus know what you meant. But, there are reasons against this:

You may be tempted to consider it stupid to write a description like
Indeed there may be cases where this level of detail is superfluous. But believe us, more often than not, it in the final consequences saves more time than it takes.

Please always be aware that often enough, the reader of your issue description does not have the same background, with respect to the particular task you're doing, that you yourself have.

Provide sample documents, if possible

If there is a problem with a particular document, then attach it. This most often allows people to really easily reproduce your problem by simply opening the attached document.

If the description how to reproduce a defect (see Provide step-by-step descriptions) exceeds a certain limit, ask yourself whether you can submit the result of the description as sample document, and attach it to the issue.

Oh, and one thing: If there is a problem on page 3 of your 1000-page diploma thesis, then please first try if the problem also occurs if you strip all pages except the third one. If so, then please simply attach the stripped version of the document, not all 1000 pages ....

Use attachments where possible

Don't paste large files into the description. For instance, if you're asked to provide a stack of a crash, copy this stack into a file, then attach this file. If you have some Basic macro or Java code which triggers a problem, copy it into a separate file, and attach this file.

The reason here is simple: A 3-pager within the description of an issue makes reading the issue really difficult. Everybody who wants to get an impression of the issue needs to scan through a lot of information which, though definitely important, is of only peripheral interest for them at the moment.

Put all relevant information into the issue

Don't use (only) links to refer to the bug descriptions. Links tend to become outdated over time, so if half a year later, somebody looks at your issue, it has become meaningless.

If there is some external resource describng your problem - fine, link it! But don't rely on links as the only mean for bug descriptions - copy the information which is necessary to reproduce the problem into the issue.


The author of the original document is Frank Schönheit. Constructive feedback is welcome. You may also consider visiting the mailing list dedicated to discussing issue handling.
Last change: $Date: 2007/03/23 09:53:23 $ / $Author: wg $

By any use of this Website, you agree to be bound by these Policies and Terms of Use

CollabNet is a trademark of CollabNet, Inc., Sun, Sun Microsystems, the Sun logo, Java, Solaris, StarOffice are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.