How to file a ticket
If you're using Sugar on a Stick or another distribution of Sugar and find something specific you think could be improved—maybe something isn't working the way you think it should work, or you have an idea for how something could be better—you can file a ticket. A ticket is a way for anyone to suggest to the software or project development community that they should work on something.
Log in to GitHub
Create a summary for the ticket
You'll notice that the first text box is for a Summary of the ticket. Sometimes the Summary is also called the Title of the ticket. This is an important part of the ticket—in fact, some people say it is the most important part—because reading the title of a ticket is how someone decides if he or she is going to work on it.
Write a ticket summary/title that describes your idea. Try to write it succinctly, so that those reading the title of your ticket will go "oh, I know what I have to work on, and why this is important - I will read more about this ticket and maybe try to fix it."
A good ticket is in many ways like a good newspaper headline.
Good newspaper headlines: (taken from http://lwn.net/ as of the day of this writing)
- SpamAssassin-milter has a remote root vulnerability
- SeaMonkey 1.x goes unsupported
- GNOME Foundation and KDE e.V. to Co-Host Conferences in 2011
Bad newspaper headlines:
- Today, bad things happened with SpamAssassin
- Stuff about SeaMonkey
- GNOME and KDE are doing a thing
Good ticket titles: (taken from http://bugs.sugarlabs.org as of the day of this writing)
- Frame: Battery icon does not update when battery is removed/replaced
- Make "keep aspect ratio" selection visible in the UI
- Drop down menus give no indication of their existence, also are too slow to load.
Bad ticket titles:
- This frame stuff doesn't work
- Make the Paint Activity better
- HELP I have a problem!!!
Describe the ticket
This section has not yet been written. If you can help, please write it!
- Include specifics on your hardware & software versions, if you know them.
- Describe what happens and what you expected to happen.
- Include steps to reproduce the situation so others can confirm and investigate your issue.
- Embed links to mailing list posts, blogs, videos, or other descriptions of the issue or problem, if appropriate.
- Please, please, please cross-reference with links to related tickets, perhaps in http://dev.laptop.org.
- Check the 'I have files to attach to this ticket' box or, on an existing ticket, the [Attach file] button.
- See BugSquad/Get Logs for how to review and attach log files.
- Sometimes screen shots of a problem will help explain it. Pressing <Alt> + 1 in Sugar captures the screen and stores a screen shot in the Journal.
Categorize the ticket
Now that you've finished writing your ticket, it's time to categorize it so that it gets to the right people when you file it. We'll walk through each of the important categorizations in turn.
The first section (highlighted in purple) is the ticket type. There are two types of tickets: defects and enhancements. Defects are things you think are broken. If you can't get something to work, that's a defect, and you should choose the "defect" option. Enhancements are ideas on how to make something that isn't broken better - maybe you have an idea for a new feature that will let you do things that you can't do with the software right now. If your ticket is an enhancement, choose the "enhancement" option.
The next sections we need to look at (highlighted in green) are the component and distribution/OS sections. Tickets specify components to tell us which part of the software or project that we should look at, and who might want to look at it. For instance, if we were working on a bicycle, you might report a bug in the "handlebar" component - that way, we know to just look at the handlebar when we're fixing things, and the people who only want to work on tires know they don't have to worry about that problem. For Sugar on a Stick, the component is SoaS.
As you file and review bugs, you can help triage bugs by finding duplicates and sharing questions and comments with the reporters and maintainers to help advance the work.
Create the ticket
It's a good idea to preview your ticket before you file it, in order to see what it will look like - click the Preview button first. You may notice formatting or other problems in the description, so take the time to review your submission because once you create the ticket, the original description can't be modified (only the Summary/Title can be changed). You can always add replies and comments that are tracked chronologically along with other field changes.
The last thing you should do is click the green Subnit New Issue button.
You're all done for now - congratulations, and thanks for your help!
The ticketing system only works if reporters, triagers, maintainers, authors, developers, and the community follow up to clarify the information and work needed and record its status.