File Bugs

This is a draft of the "How to File Bugs" document.

Why file bugs?

Sometimes the devleopers are too busy to fix things as they are reported. Up until recently, many people reported bugs to the developer mailing list or our IRC channel. Bugs reported in this manner may not get attention right away, and the details of the bug may be lost to time. Filing bugs in Bugzilla allows you to report the problem in a manner that lets the devs know something is broken, but give them time to finish other tasks, have a life, etc..

Bugs to not report in Bugzilla

• Build breakages on the common platforms (Windows, Linux). Please report build breakages on IRC, or to the ros-dev mailing list.
• Features reported to be in the next version of windows (WinFS, etc..)

How to File (good) Bugs

Gather Information

When you encounter a problem in ReactOS, there are a few basic things we need to know.

• Has this bug already been reported?

Please take a few minutes to look over the exisiting open bugs. If a bug has been reported, you can simply update the exisiting bug with any further details you may have uncovered. If nothing else, you can update the bug with the revision number, so we know this is still happening.

• Your hardware configuration

If you are running on real hardware, gather information about specific hardware configuration. On Windows, use the standard tools: Device Manager, msinfo32, dxdiag, etc. If you are using linux, 'lspci' or 'cat /proc/pci' would be a good place to start. If you are using a virtual machine, please note the virtual machine software version in addtion. This is extremely important in diagnosing boot or install errors.

• The version of ReactOS you are running

If you are running a release from sourceforge, then we need to know the version (i.e. 0.2.7) If you are running a debug build from SVN, we need to know the revision, this can be obtained from the 'ver' command in a command prompt. 'ver' will report something like "Version 0.3-SVN 20050815-r17402". The rXXXXX number is what we need.

• What you were doing when the crash happened

This is probably the MOST important thing you need to report. If we cannot reproduce the bug, then it will be nearly impossible to diagnose and repair. Please take the time to reproduce the crash before filing the bug, and when you can consistantly reproduce the bug, write a detailed description on how to reproduce it.

• Any debug messages output by ReactOS

If you experience a crash (BSOD), please take the time to document the crash details. If you are running ReactOS under a virtual machine, take a screenshot of the crash. Please see the Debugging section for further details on the debug output.

• The version of the application you are running

If the crash is related to your favorite windows app, please report what version of that app you are using, and where you downloaded it from.

• Screenshots of graphical bugs

A picture is worth a 1000 words, and when it comes to debugging graphical problems, possibly more. Bugzilla allows you to attach files to bugs, so if you can get a screenshot of a bug, please do so.

Using Bugzilla

To use the ReactOS Bugzilla, you need to create an account on the main reactos.com site, which will allow access to bugzilla. (*Update this after the new site is in place*)

The Bugzilla form is pretty straight-forward, but here are some tips:

• Version: If you are using a release, please indicate the version you are using. If you are using a build from SVN that is newer than the latest release, please use the version "HEAD"
• Component: This is the "area" of ReactOS where the bug is located. The Component link next to the select box explains each component. If unsure, please guess, we can change it later.
• Platform: Please note on what type of hardware you experienced this bug. If unsure, use the default "x86 Hardware"
• OS: The OS on which the bug happened. Usually will be "ReactOS", but if you were testing ReactOS components on Windows, please indicate which version.
• Severity: This indicates how "bad" the bug is. For most bugs, please leave this at "normal", we will adjust the severity as needed. Please do not file bugs as "blocker", we use blocker level for the worst bugs that must be fixed for the next release. The Testing Coordinator or Devleopers will determine if a bug is a blocker.
• Assigned to: Please leave blank
• URL: If this bug is against the "Online Services" component, please give the URL of the problem page.
• Summary: A short description of the bug. When doing a bug listing, this is the only bug desctiption shown. Please make this as clear as possible, since other users reporting bugs will need to check if a bug has already been filed.
• Description: The detailed description of the bug, please place all the information you have gathered (above). If you need to attach a file, fill out and submit the bug, then add the attachments.
• Depends On: Bugs that need to be fixed in order to fix this bug. We will generally fill this in when needed.
• Blocks: This bug needs to be fixed in order to fix other bugs. We will fill this in as needed.

Some notes about Bugzilla

• After a bug is filed, or anytime it is updated, an email is sent to the ros-bugs mailing list
• The words "attachement" and "bug" are automatically linked in the description test. So if you say "This may be related to bug 1234", "bug 1234" will automatically become a link to bug 1234.