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.
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
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.
For those of you who like it short and simple:
- One problem - One issue
- Provide a meaningful summary
- Provide step-by-step descriptions
- Provide sample documents, if possible
- Use Attachments where possible
- Put all relevant information into the 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.
If you don't follow this rule, be prepared for people asking you to split up your issue.
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)"
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
- 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.
- 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
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.
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 ....
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.
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.