All bug reports, patch submissions and feature requests are kept in the issue tracker “Trac” at 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.

In order to create a new ticket, you must 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 forums, where your user account is managed and kept. Login with the same username and password at Trac, then check in the 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 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:

1. Describe what you do to reproduce the initial situation.
2. Describe what you expect to happen.
3. 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.

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.

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.

Please be very conservative with the priority setting, normal is almost always right.

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.

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

Set the proper version, typically svn-head if you're working with the subversion repository.

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

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.

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.

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 cafuticketworkflow.dia, and another version that has been automatically generated with GraphViz is here.

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 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 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!