wiki:APP_BUG_REPORT_FORM_R0
Last modified 16 years ago Last modified on 06/02/09 16:22:26

Error: Macro BackLinksMenu(None) failed
compressed data is corrupt

Error: Macro TicketQuery(summary=APP_BUG_REPORT_FORM_R0, format=table, col=summary|owner|status|type|component|priority|effort|importance, rows=description|analysis_owners|analysis_reviewers|analysis_score|design_owners|design_reviewers|design_score|implementation_owners|implementation_reviewers|implementation_score|test_owners|test_reviewers|test_score|) failed
current transaction is aborted, commands ignored until end of transaction block

Analysis

Overview

this should be invokable  from help menu, or on internal error

The Bug report form eases communication between users and developers. The form contains:

  • A log containing information useful for debugging. This field is read only.
    • including exception details, Java and OS version, log file, etc.
  • A custom text field containing user explanation on what happened. This is not a required field.
  • A text field for the user's e-mail address.
    • This should be preserved in order to be easier for the user when he/she reports a bug again
  • A warning that user information such as working path and filenames will be sent.
    • This probably will be frightening for the user but it is needed, if we can't go around the private information

Behavior:

  • The bug report form appears automatically when an expected error occurs (exceptions, etc).
  • The bug report form may be forced by the user using "Help->Send an error report"

The goal of this revision is to provide the client side of bug reporting. (I.e. the bug report couldn't be sent automatically, but can be saved as a file).

Task requirements

  • Create an extension for the "Send an error report" item for the Help menu.
  • Implement invoking the Application bug report form automatically on catching an exceptions.
  • Create the bug report form
    • A dialog
    • Titlebar
    • Text fields
      • The content of the e-mail field should be saved in a config file. First time the form is opened, the user enters his/her e-mail address. Next time the field displays the same address.
    • Report button - in next revision
    • Save-as-file button - if the form is invoked automatically on error; saves the report as a plain text file (a file dialog is opened and the user selects a path for the file)
      • Plain text file with .log extension. This file can be used when sending bug reports from Help menu entry or submitting bugs on the site.
    • (when implementing the server side) Load-report-from-file button - if the form is invoked manually - the user can attach already generated report file.
    • Attach-file button - allows the user to attach a book/video/etc. that causes Sophie to crash.
    • Cancel button - closes the form without saving or sending the report
  • Bug report contents (in this order):
    • Exception's stack trace if the form is invoked automatically on error.
    • Current date and time.
    • (in next revision - current version of Sophie)
    • Sophie's log file (currently it is not in distrib directory).
    • System properties such as operating system version, version of Java, ...
    • User's e-mail address.
    • User's explanation (which can be empty).
  • Titlebar must contain Bug number or exception description.

Task result

Code.

Implementation idea

  • This is a draft diagram. For now, the checkbox is obsolete as it is hard to implement and not much useful. Instead, there is a text field for the e-mail address.

source:trunk/sophie2-platform/doc/spec-diagrams/BugReport.png

  • Note that on the diagram there is no Save to log file button, but it is part of the task requirements.
  • Create a handler for unhandled exceptions. Use Thread.setDefaultUncaughtExceptionHandler.
  • Save the e-mail address in a config file in distrib directory. In next revisions save it in application's configuration file.
  • Get the contents of Java system properties like "os.name", "os.arch", "os.version", etc.

UserBugTracking by Dan Visel - contains detailed information about bug reporting in Sophie
PLATFORM_STANDARDS_MANUAL_TESTS

How to demo

  • Open Sophie 2.
  • Perform an action that throws an error (if you don't know such, manually invoke the form by the Help menu).
  • Enter something in the explanation text field.
  • Save the error report in a file.
  • Open the file to show the collected information.

Design

  • Create a package org.sophie2.main.func.help.bugreport in main.func.help module.
  • Create a menu item "Send an &Error Report..." in org.sophie2.main.func.help.menuitems and attach it to the Help menu.
  • Create a class org.sophie2.main.func.help.bugreport.BugReport that represents the bug report data and has the following properties:
    • String property stackTrace - can be empty
    • String property date - report's creation date and time in ISO format.
    • String property log - the contents of Sophie log files
    • String property systemProperties - java system properties, serialized (​http://java.sun.com/j2se/1.4.2/docs/api/java/lang/System.html#getProperties())
    • String property email
    • String property userExplanation - can be empty
    • String property attachment - absolute path of attached file. Can be empty
    • String property technicalInformation - auto property which contains all technical data in this report, serialized to String. Includes everything that is automatically collected - stack trace, log files, system properties.
    • String method getContent() - gets all data in this report, serialized to String.
  • Create a class org.sophie2.main.func.help.bugreport.BugReportDialogInput that extends DialogInput<Void>:
    • private final BugReport bugReport;
    • private final String windowTitle;
  • Create a class org.sophie2.main.func.help.bugreport.BugReportDialog that extends org.sophie2.base.dialogs.Dialog<BugReportDialogInput, Void>.
    • Use BoundTextFields.
      • The e-mail text field should perform validation using regular expression.
    • BugReport property
    • String property title
    • JDialog property swingComponent.
    • enum EventIds: CLOSE, SAVE_TO_FILE, ATTACH_FILE, EMAIL_CHANGED
    • Register the dialog in the help module.
  • The e-mail address will be stored in a plain text file.
    • Currently there is no configuration file, so the proposed solution is temporary and should be replaced after the configuration file functionality is implemented.
    • Use FileEntryManager's methods getReadableFileEntry and getWritableFileEntry.
  • Move Sophie log files to distrib directory:
    • Edit log4j.properties for author and reader, set log path to be in distrib/log.
    • Now log files can be read using FileEntryManager.
  • Create a controller enum org.sophie2.main.func.help.bugreport.BugReportLogic
    • SHOW_BUG_REPORT_FORM: this should be called when the menu item is selected. Calls BugReportLogic.showBugReportForm(null); (null, because no exception is thrown)
    • SAVE_REPORT_TO_FILE: opens a file dialog, saves the result of BugReport.getContent() and closes the form.
      • Use UTF-8 encoding.
    • ATTACH_FILE: opens a file dialog, sets the attachment field in the bugReport property of the event source (BugReportDialog).
    • CLOSE: closes the form.
    • SAVE_EMAIL: invoked when the user enters a valid e-mail in the form. Saves the address as described earlier.
    • static void showBugReportForm(Throwable throwable): calls collectReportData(throwable) and opens the form using DialogManager.
    • static BugReport collectReportData(Throwable t): collects all required report data:
      • serializes the throwable's stack trace to string.
      • gets current date and time.
      • reads all log files (using listFileEntries in FileEntryManager).
      • gets all system properties
      • reads the e-mail address from a file
      • the explanation is an empty string
      • the attached file is null
  • Create a class org.sophie2.main.func.help.bugreport.SophieExceptionHandler that implements Thread.UncaughtExceptionHandler.
    • In uncaughtException(Thread t, Throwable e) call BugReportLogic.showBugReportForm(e);
  • Register that handler by invoking Thread.setDefaultUncaughtExceptionHandler(new SophieExceptionHandler()); in HelpModule.doStart.

Implementation

  • Bound controls should be fixed in another task:
    • Validation is not performed at startup (for example, when the form is opened).
    • Validation status should be visible from outside of the controls.

Merged to the trunk in [3103] and [3104].

Testing

Comments

danvisel: A note on this: I think it's important to get the user's email address in some way. In Sophie 1, 95% of the time, users just clicked "okay", we were sent a bug report, and then couldn't do very much with it because we didn't know anything about the book, what was being done, and we didn't have any way to contact the user about it. I think in the pre-release versions of Sophie 2 we should get the user's email address the first time they start the program; this should be sent with the bug report so we have some way to get more useful information for debugging.