Skip to content

start:

Basic IssueTracker rules

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)

  • community members who performe triage on defects
  • developers who finally fix the defect
  • sometimes developers who need to do preliminary work
  • QA engineer(s) who needs to verify the fix
  • everybody who has the same problem and tries to understand whether
    • your defect also describes his/her problem.
    • or whether your issue is one they like to vote for
  • possibly a user experience team member evaluating a feature request
  • possibly a release team member evaluating whether the defect is important enough to be included in some maintenance update such as 1.1.1.
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:

  • The more crowded an issue is, the more likely is it that some problems may get lost over time.
  • Different problems are most likely to be handled by different people (both in engineering, where the problem is fixed, and in QA, where it's verified). The more problems you put into the issue, the more difficult is this issue to handle for all involved parties.
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

  • easily recognize an issue in a list of dozens of others
  • find an issue. Since duplicate issues are draining a lot of work from engaged community members, we always ask people to look whether the problem, which they are going to submit as issue, is already known and reported. Of course this works best if the summaries of the existing issues are as descriptive as possible.
  • judge the importance of an issue. "Spreadsheet problem" is less likely to be handled appropriately than "Spreadsheet: Data loss when ...." or "Label X in dialog Y has a wrong offset (2 pixels)"
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:

  • Though the problem may seem simple to you, there may be deeper reasons which prevent others from trying. For instance, it may crash only if you customized the "Bold" icon into a non-standard toolbox. In such a case, people will try for no avail, without encountering your problem at all, and thus waste time.
  • Writing down exactly what you did costs you some time once, but every reader (there may be numerous during the lifetime of an issue!) needs time for guessing and trying. It's more efficient if you do it, and QA and engineering can concentrate on fixing the problem, instead of performing triage on it.
  • There are a lot of scenarios where the set of possibility is much larger. Formatting a text as bold may be simple and easy (though you've already seen that there are at least 5 ways to do so), but other tasks may require more steps which you implicitly know, but your reader doesn't.
You may be tempted to consider it stupid to write a description like
  • open a new writer document
  • enter some arbitrary text
  • select the whole text via "Edit|Select all"
  • from the context menu of the text, chose "Style|Bold"
  • => OpenOffice.org crashes
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 describing 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: 2008/06/20 08:20:33 $ / $Author: fs $