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.)

Here are a few ways to let us know about a bug:

Quick and easy way: tell somebody

What you do: post to devel@lists.laptop.org only.

What we will do: approve your posting even though you may not be subscribed, review what you said and figure out if anything looks truly interesting, and perhaps enter into discussion, though we might not say anything about things we already know about,

Less quick: Trac and run

What you do: register in trac, login, and make a new ticket without any research.

What we will do: check for duplicates and close it if it is duplicate, then we'll either reproduce it and begin work on it, enter into discussion with you, or eventually close it as unreproducible.

Harder but more helpful: Trac with care

If you can verify that the problem is to do with Sugar alone, and nothing to do with the XO at all, then report a bug in the Sugar Labs bug tracker.

The same can be said of any bug that is clearly in the Fedora Gnome scope, and nothing to do with the XO at all. Go to the Fedora Project bug tracker.

But if you're sticking with us ... 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.
• If you want to alert a particular developer, you can enter their Trac usernames or email address in the Cc: entry box (separated by commas).
  This mechanism can also be used for the Owner (Assign to: or reassign to:) entry.

• 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 Browse activity is most helpful for uploading the logs tarball as an Attachment to a Trac bug ticket.

• Attaching Sugar logs to tickets explains how to turn on more detailed logging

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/Development_Team/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.