User Tools
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision | |||
|
cppdev:submittickets [2017-02-05 17:15] Carsten deleted obsolete page (it's all done via the Bitbucket Issue Tracker now) |
— (current) | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | ====== How to Submit Tickets ====== | ||
| - | |||
| - | All bug reports, patch submissions and feature requests are kept in the issue tracker "Trac" at [[http://trac.cafu.de|trac.cafu.de]]. | ||
| - | Trac refers to all sorts of issues collectively as "tickets". | ||
| - | |||
| - | This page explains how tickets are created and filled-in the most effectively. | ||
| - | |||
| - | |||
| - | ===== Overview ===== | ||
| - | |||
| - | In order to create a new ticket, you must [[http://trac.cafu.de/login|login to Trac]] first. | ||
| - | |||
| - | If this is your first visit to Trac, note that the Trac login is connected to the forum database: You only have to register yourself once at the [[http://forum.cafu.de|forums]], where your user account is managed and kept. Login with the same username and password at Trac, then check in the [[http://trac.cafu.de/prefs|Preferences]] if your email address has been overtaken into the Trac session correctly. Optionally fill in your full name as well. | ||
| - | |||
| - | Before creating a new ticket, //use the search functions// in order to make sure that the bug or proposed enhancement has not already been submitted: | ||
| - | * Use the [[http://trac.cafu.de/search?ticket=on|search]] for global search. | ||
| - | * Use //queries// to search for strings | ||
| - | * in ticket summaries (example: [[http://trac.cafu.de/query:status!=closed&summary~=soundsys]]) or | ||
| - | * in ticket keywords (example: [[http://trac.cafu.de/query:status!=closed&keywords~=SoundSys]]). | ||
| - | If you are unsure whether you encountered the same bug, open a new ticket and add mutual links to both tickets | ||
| - | (entering a ticket number like ''#1234'' into a ticket description is automatically converted into a hyperlink to ticket number 1234). | ||
| - | |||
| - | If you want to express interest in a bug that is already submitted, add yourself to the CC list or add more details. Or even better, try to fix it. ;-) | ||
| - | |||
| - | When reporting a bug, it's usually obvious to the submitter (you) what the problem is. Unfortunately it's quite often less obvious to us (the developers) and the chances of a bug being fixed decrease dramatically if we can't even understand what it is. So please follow this general template when reporting the bugs, with the possible exception of really trivial and self-explanatory ones: | ||
| - | - Describe what you do to reproduce the initial situation. | ||
| - | - Describe what you expect to happen. | ||
| - | - Describe what happens. | ||
| - | Variations are possible, of course, but please follow the above steps if in doubt. Also see the descriptions of the individual fields below for more details. | ||
| - | |||
| - | |||
| - | ===== Ticket Fields ===== | ||
| - | |||
| - | === Summary === | ||
| - | Provide a concise and meaningful title. | ||
| - | You may assume that the **Summary** field will be viewed together with **Type** and **Component**. | ||
| - | For example, you don't need to mention "CaWE" in the summary if the component is set to ''CaWE''. | ||
| - | |||
| - | === Description === | ||
| - | Make sure to provide enough details and context so that we can understand the issue comprehensively -- only then are we able to help you. | ||
| - | |||
| - | We don't need lengthy texts, and if you attach a well-documented patch and the other fields contain all relevant information, you may need no description at all. But if you're filing a bug report, include instructions on how the bug can be reproduced. If you're proposing a new feature or enhancement, describe it in sufficient detail. | ||
| - | |||
| - | === Priority === | ||
| - | Please be very conservative with the priority setting, ''normal'' is almost always right. ;-) | ||
| - | |||
| - | === Component === | ||
| - | Select the Cafu component that your ticket is related to from the drop-down list. | ||
| - | For ticket reviewers, **Component** is the most important drop-down field. | ||
| - | |||
| - | === Keywords === | ||
| - | Optionally fill-in any keywords that seem appropriate. | ||
| - | When you refer to C++ classes, use their full names (e.g. ''EntHumanPlayerT'', not ''humanplayer'' or ''EntHumanPlayer''). | ||
| - | |||
| - | === Version === | ||
| - | Set the proper version, typically ''svn-head'' if you're working with the subversion repository. | ||
| - | |||
| - | === CC === | ||
| - | The [[http://www.cafu.de/support/mailing-lists|cafu-dev mailing list]] is always notified about new ticket creations and ticket changes. Therefore, we recommended that you subscribe to cafu-dev for keeping informed about all changes. | ||
| - | |||
| - | If you prefer to not subscribe to cafu-dev but want to get email notifications about changes to this ticket, add yourself to the **CC** list. This works both with tickets opened by you or by somebody else. | ||
| - | |||
| - | === Platform === | ||
| - | If relevant, make sure that you specify the exact OS name and version, 32- or 64-bit, compiler version, etc. in the **Description** text as well. | ||
| - | |||
| - | /* === Patch === | ||
| - | Attaching a patch that fixes the bug or implements the enhancement you propose will give a higher priority to your ticket. | ||
| - | Please read [cppdev:SubmitPatches] for the details. */ | ||
| - | |||
| - | === Milestone and Assign To === | ||
| - | Please don't set these fields at all, they are meant to be used by developers. | ||
| - | Setting them doesn't help with getting the ticket addressed sooner, quite to the contrary: it might slow things down as a developer would have to spend time with (re-)setting them properly. | ||
| - | |||
| - | |||
| - | /* | ||
| - | ===== Things to Avoid ==== | ||
| - | |||
| - | Here is a list of things that people sometimes do in the hope to increase the urgency of their ticket or to get it addressed sooner: | ||
| - | |||
| - | * Not providing enough details about the problem. | ||
| - | * Opening multiple identical (or very similar) bug reports about the same problem, usually still without providing enough details. | ||
| - | * Incrementing the bug priority or moving its target milestone, typically even though it was already reset by a developer before. | ||
| - | * Use of slang language, special or all capital letters, xxx | ||
| - | * Putting strongly-worded requests to fix your bug as soon as possible (usually in capital letters) in the summary or description. | ||
| - | |||
| - | Any of these typically just has the opposite effect: A developer has to spend time with re-setting or fixing the ticket, slowing things down. | ||
| - | */ | ||
| - | |||
| - | |||
| - | ===== Ticket Workflow ===== | ||
| - | |||
| - | {{ :cppdev:cafuticketworkflow.png?240|The Cafu ticket workflow.}} The diagram at the right presents the states that a ticket can be in, and the transitions that indicate how a ticket changes from one state into the next. | ||
| - | |||
| - | The first state of a new ticket is always **new**, and it is up the developers to initiate transitions to other states. When a ticket has reached state **closed**, its objectives have been met and its issue is being considered resolved. | ||
| - | |||
| - | The source file of the diagram is {{:cppdev:cafuticketworkflow.dia}}, and another version that has been automatically generated with GraphViz is [[http://docs.cafu.de/_media/cppdev:cafuticketworkflow-graphviz.png|here]]. | ||
| - | |||
| - | |||
| - | ===== Final Note ===== | ||
| - | |||
| - | Cafu is, to a large degree, a community project, and we need and very much appreciate your help. | ||
| - | Here are just a few examples on what you can do: | ||
| - | |||
| - | * Create and submit [[cppdev:SubmitPatches|patches]]. | ||
| - | * If you see that a bug that you reported in the past was fixed, but the ticket is still open, close it. You can easily list [[http://trac.cafu.de/query:status!=closed&reporter=$USER&group=component|all open bugs you reported]]. | ||
| - | * We really welcome other help with the existing bugs as well: for example, verifying that the bugs can still be reproduced, commenting on potential workarounds and so on. | ||
| - | |||
| - | We're looking forward to your tickets! :-D | ||