Menu ▾ ▴

Guides-Reporting Bugs

raspopov

Reporting Bugs

What should I include in a bug report as a minimum?

Your bug report should include:

  • The build of Shareaza that you are running.
  • The operating system of your PC.
  • A description of the bug. Where possible include screen captures with highlights and notes to help communicate and illustrate the problem/bug.
  • A description of events/actions at the time the bug was observed.
  • If possible, a description of events/actions that can reproduce the bug.

Read How to Report Bugs Effectively (Third Party Site) to learn how to effectively report bugs.

What severity level should I use when reporting bugs?

Please use the following as a guideline for choosing severity levels for bugs on the bug tracker:

  • Critical
    • constant crashing/assertion error/freezing
    • prevents files from downloading/uploading
    • corrupts/deletes library files
    • makes shareaza completely unusable
    • blue screen of death
    • breaks internet connection
    • blocker - would postpone release
    • crashes computer/windows
    • causes computer to burst into flames
  • High
    • crash/assertion error occurs occasionally
    • crashes on a certain event (eg. deleting a file)
    • important feature is broken (eg. opening library files)
  • Medium
    • minor feature is broken (eg. import partials)
    • bugs that can be fixed through other means (eg. ignore local IPs broken -> add security filter for local IP addresses)
  • Low
    • untranslated text strings
    • minor layout bugs
    • broken p2p chat features
    • bad artwork in skins(eg. background not transparent, 2px cropped off image)
    • feature can be removed from release version if required
  • Very Low
    • minor typos/grammar mistakes
    • broken easter eggs

How do I insert images in my bug report on the bug tracker?

The bug tracker does not support inline insertion of attached images the way the forum does nor does it support the use of the [img] tag for inline insertion of images eg. [img]<http://img178.imageshack.us/img178/8352/myimage.png[/img>]. You can add images to a report/comment by either attaching the individual image files or including image(s) in an archive file eg. Shareaza_error_report_090224-053106.zip

What is BugTrap?

BugTrap is a newly implemented feature in current code debug builds introduced on 2009-02-22, revision 7705. It is a replacement for the previously used DrWatson? that can generate useful debugging information for assertion errors and crashes including error/crash logs for inclusion in bug reports.

An email address/BugTrap server has not been set up as yet for this feature in debug builds to automatically submit bug reports for assertion errors and crashes. Please log bug reports manually on the bug tracker by attaching the generated BugTrap error report zip file.

BugTrap in current debug builds gives you the option to creates crash/error logs locally on your PC for both assertion errors and crashes. BugTrap generates a zip archive file e.g. Shareaza_error_report_090224-053106.zip with 3 files inside: crashdump.dmp (Dr.Watson minidump), errorlog.xml (modules list, version info etc.) and settings.reg (HKCU\Software\Shareaza key dump).

How do I add the environment variable required for [BugTrap] to Windows?

BugTrap, specifically dbghlp.dll uses Microsoft Symbol Server. With it, users can download symbols from Microsoft for system DLLs to produce detailed call stack logs. You must ad the environment variable _NT_SYMBOL_PATH = SRVC:\WINDOWS\SYMBOLShttp://msdl.microsoft.com/download/symbols to Windows in order for this feature to work correctly.

You can add the environment variable by:

  1. Right-click My Computer and select Properties.
  2. This will bring up the "System Properties" dialog box
  3. Select the Advanced tab in the System Properties dialog box.
  4. Click Environment Variables.
  5. Under System Variables, click New.
  6. In the Variable Name field, type "_NT_SYMBOL_PATH".
  7. In the Variable Value field, type "SRVC:\WINDOWS\SYMBOLShttp://msdl.microsoft.com/download/symbols".
  8. Click OK to finish adding the environment variable.

How can I test BugTrap in Shareaza?

You can produce a test crash (Access Violation error) and test BugTrap error reports in a current debug build of Shareaza by:

  • Going to the "Help" menu and selecting "About Shareaza..."
  • This will bring up the "About Shareaza" dialog box
  • At the bottom of the dialog box there is a URL "http://shareaza.sourceforge.net/"
  • Right click on this URL while holding down the Shift key

What do I do if [BugTrap] is not generating all 3 files in the zip archive?

If [BugTrap] is not working correctly for you in generating all 3 files (crashdump.dmp, errorlog.xml, settings.reg) in the zip archive check the following:

  • Check you have system dbghelp.dll file in your Path or Shareaza folder. If not, download dbghelp.dll from SVN and place it in your Shareaza folder.
  • Check you have Shareaza.pdb file on the same folder as Shareaza.exe, usually both are in your Shareaza folder. If not install/re-install latest VS2008 debug build.

What is an assertion error?

An assertion error is not a crash. An "assertion" is coding put into the program to make sure that code inputs are generated as expected and that the code is on the right track. When the program is running, it will throw up an assertion error if one of the coded "assertion checks" fails. Typically assertions are only processed in debug mode (when running a debug build) so that developers can identify and fix serious errors in the program before compiling an optimized release version.

What do I do if I get an exception (assertion error or crash), and how do I report it?

If you are not running a current debug build and are experiencing crashes with an older build of Shareaza, you should install a ["Development, Bug Reporting, and Debug Builds" current debug build].

If a current debug build throws an assertion error or crashes, you will get the following BugTrap dialog box.

It is very important to note the "Exception Reason" which is highlighted below and is used in helping us identify and differentiate errors.

http://img82.imageshack.us/img82/9753/bugtrap.png

Two things you will need to do with this dialog box:

  1. Select and copy the "Exception Reason" text in the dialog box for inclusion in your bug report.

e.g. Shareaza.exe caused ACCESS_VIOLATION in module "D:\Program Files\Shareaza\Shareaza.exe" at 001B:00D5E268, CAboutDlg::OnRButtonDown()+152 byte(s) in "d:\documents and settings\george\my documents\visual studio 2008\projects\shareaza\shareaza\dlgabout.cpp", line 165+3 byte(s)

  1. Click on the "Save" button to save the [BugTrap] error report zip file.

e.g. Shareaza_error_report_090324-062151.zip

If you forget to select and copy the "Exception Reason" text in the dialog box for inclusion in your bug report, or you want to check the "Exception Reason" information of a [BugTrap] error report submitted by someone else, you can go into the BugTrap error report zip file and view the errorlog.xml file. Look for the <error> block to find the "Exception Reason" information.

e.g. 

  <error>
    <what>ACCESS_VIOLATION</what>
    <process>
      <name>Shareaza.exe</name>
      <id>3956</id>
    </process>
    <module>D:\Program Files\Shareaza\Shareaza.exe</module>
    <address>001B:00D5E268</address>
    <function>
      <name>CAboutDlg::OnRButtonDown</name>
      <offset>152</offset>
    </function>
    <file>d:\documents and settings\george\my documents\visual studio 2008\projects\shareaza\shareaza\dlgabout.cpp</file>
    <line>
      <number>165</number>
      <offset>3</offset>
    </line>
  </error>

The "Exception Reason" information is used for two things

  • to check against already logged reports on the bug tracker to see if this error has already been logged
  • for use in the labeling of exception bug reports

If the "Exception Reason" specifies a "BREAKPOINT" error then this tells you that this is an assertion error. If the "Exception Reason" specifies any other error, e.g. "ACCESS_VIOLATION" error, then this tells you that this is a crash.

Exceptions are identified by the error type, the file, line number of the error. For example an appropriate label for an assertion error report would be "BREAKPOINT - librarymaps.cpp - line 131" or for a crash report "ACCESS_VIOLATION - dlgabout.cpp - Line 165".

With exceptions, even if the actions leading to the error or the error log files generated vary, we still post all related instances under the one bug report. All relevant error logs and information should be posted under the same bug report for the same exception (assertion error or crash). Note that even though the error might be occurring in the same part of the code each time, the observed actions/behaviors leading to the error may well vary. It is important to note variations in actions/behaviors leading to the error.

Check to see if the particular exception you are getting has already been reported in a bug report on the bug tracker.

If it is already reported, you can add your information and [BugTrap] error report zip to the existing bug report in a new comment making sure you specify the build you are using (e.g. r7760).

If it is not reported, create a new bug report adding your information and BugTrap error report zip. It is also helpful if you can include the "Exception Reason" information as this will help everyone more easily confirm/identify the error and help avoid the creation of duplicate bug reports.

If you are still unsure as to whether your bug does or does not correspond to an already existing bug report, just create a new one. The development team will look through the bug reports and determine if it is a duplicate.

What do I do if Shareaza hangs without generating a BugTrap error report, and how do I report it?

Use a free program called DebugView from Sysinternals to capture a debug log.

The reporting process is the same as that listed above for exceptions.

Related

Devs Wiki: BugTrap
Devs Wiki: Guides