Reporting bugs

Like all open software, the software on the XO is constantly ready for improvement. While the basic functionality is now good, the truth is that many components are only at a beta-testing quality level. That means that we appreciate all bug reports from our users. (In fact, we hope that you will think of the bugs you find as opportunities to help us improve, rather than just nuisances.)

There are two ways to let us know about a bug

Quick and easy way: tell somebody

The easy way: write an email to "help AT laptop.org".

Harder but more helpful: Trac

The harder-but-more-helpful way: First search the Trac bug database at http://dev.laptop.org/query to see if the bug has already been reported. If it has not, register yourself on that site and submit the bug. Some useful hints:

• The main fields to fill out are:
  • summary - Short descriptive summary
  • description - Please make sure the build number, firmware version are right up front (preferably in the first line all by themselves); then a step by step description of how to recreate the issue. This is the most important thing you can spend time on since almost any bug can be fixed if it can be recreated... and many bugs will languish with no work if they cannot.
  • type - defect if it does the wrong thing, enhancement if it doesn't let you try to do a thing
  • component - use the pull down and try to identify the component. If you don't know, leave the default, 'not assigned'
  • priority - how important was this to your work? This might be changed by the triage team, but if this was really critical for you, please convey that by bumping up the priority.
  • A triage team will help with which release to put it in, and may add other notes or ask for more info. Put your user name in the cc field to get updates on the bug.

• Follow How to check the OS and firmware versions to determine the version you're running. Always try to include this info at the top of the description.

• If an activity crashed, you can often find a log file, and we would love it if you'd post the important parts of that with your bug. You can use the Log viewer activity. Find the log that corresponds to your application and look for sections that start with "Traceback (most recent call last):" and end with an unindented error name and details. (For older logs, you can use the Terminal activity to browse subfolders of /home/olpc/.sugar/default/logs)

• There is a log file gathering tool which collects various potentially-interesting log files and bundles them up into a compressed archive for efficient uploading to the bug-slaying wizards who watch Trac. The tool is called olpc-log and you can run it from a Terminal or console like this:

$ sudo olpc-log

This will create a tar archive in your default directory (usually /home/olpc ). If you want to explore it, extract it into a scratchpad directory like this:

$ mkdir junk
$ cp logs* junk
$ cd junk
$ ll
$ tar -xf logs*
$ ll
$ more */*

For more info, type:

$ olpc-log --help

The Firefox activity is most helpful for uploading the logs tarball as an Attachment to a Trac bug ticket.

Hardest but most useful: Fix it yourself.

Much of our software is designed to be hacked and debugged directly on the XO. If you discover a problem and feel like contributing directly to its diagnosis and solution, please, step right up!

Source code is readily available on the XO (for most of Sugar) and from places like http://dev.laptop.org and http://cvs.fedoraproject.org (everything else).

http://www.sugarlabs.org/go/DevelopmentTeam/CodeReview gives some great hints on how to submit improvements to Sugar. In general, all patches are welcome on our mailing lists. Finally, patches can be contributed directly to Fedora or to the actual upstream projects included in Fedora.