From BroWiki

This page summarizes some guidelines about using the Bro Issue Tracker. Please make sure you follow the instructions to ensure that your input finds the right person.

Contents 1 Ticket Work-Flow 1.1 Filing a New Ticket 1.2 Special Case: Filing Patches 1.3 Dealing with Existing Tickets 2 Useful Mark-Up 2.1 Insert example code 2.2 Refer to another ticket 2.3 Refer to a Subversion revision (aka changeset)

Ticket Work-Flow

Generally, please note that unfortunately the Bro team does not have the resources available to address all tickets immediately. One of the main objectives for maintaining a tracker is having a record of things which need work even if we can't fix them right now. If a ticket does not see a quick resolution, do not take that as an indicator that we don't consider it important. (Otherwise it would have been closed already :).

If you want to help Bro development, feel free to browse through the tickets, see what you can work on, and then file patches as described below.

There is mailing list receiving all Tracker updates. Feel free to subscribe.

Filing a New Ticket

Everybody can file a new ticket, even without having an account on the tracker. When filing a ticket, please make sure to include as much information as possible, in particular when reporting a problem. It's crucial to select the right category:

• a problem is something not working as expected, or looking different than it should.
• a feature request is a enhancement you would like to see (but not a problem in existing functionality.)
• a task is a "to do" entry that somebody (ideally you!) is planning to work on. For a task it's often already clear how to address the issue, and if so include that into the ticket. This category is primarily for developers. If you are filing a task for yourself, assign the ticket to you.
• a patch is a source code change you'd like to see applied to the specified component/version.

Please also select appropriate components (if in doubt, use Bro), and the Bro version the ticket applies to. When selecting a priority, please reserve high for really important stuff. Also, in general it's best to avoid assigning tickets to specific persons unless you're really sure about who's going to work on it.

Note that a new ticket will likely be moved into state seen rather soon, indicating that one of the developers has taken a look at the ticket. This will happen even if the ticket cannot be addressed immediately.

Special Case: Filing Patches

When filing a patch, the ticket must come patch file attached to the ticket. Patches should be considered complete at the point of filing the ticket. If it turns out later (but before the patch has been applied) that further changes are required, update the the ticket and replace the attachment. Once the patch has been applied, the ticket will be closed. If you need to make further changes, do not reopen the ticket but file a new one; refer to the initial ticket in its description.

If a patch resolves an issue described by an existing ticket, you need to file a new ticket for the patch. Close the existing ticket (if you have the permissions to do so) and refer to the new ticket in its description. Likewise, when opening the new ticket, refer to the one it addresses for reference.

Usually, patches should be filed for the Bro version to which they apply. We use one special convention however: patches files for trunk and assigned to Vern are considered finished and sufficiently tested for direct integration into trunk and thus the next release. Only Bro developers should assign patches to Vern in this way.

Dealing with Existing Tickets

You need to be a registered developer to change the status of an existing ticket. Here are some guidelines for the general ticket work-flow:

• When a ticket is new, it should be inspected by one of the developers rather soon and have its state changed as appropriate. If there is no immediate action to be taken, change the state to seen as an indicator that the ticket has been noticed and is considered appropriate for further inspection in the future. If the ticket does not appear to be relevant at all, close it right away.

• When you believe somebody particular should look at a ticket, assign it to the person (who might be yourself!). If you accept a ticket (either after it has been assigned to you, or directly), you are considered in charge of it and are responsible for making sure that it will be closed eventually.

• When a ticket is ready to be closed, declare it as resolved and include a reason for doing so. In particular, when you have applied a patch as requested by the filer, close the ticket.

• When you believe that more information is needed to address a ticket, change its status to information needed. Feel free to closed tickets in this state when they don't see any timely response.

Useful Mark-Up

Below is some useful mark-up for writing ticket descriptions. There's much more information about Trac's mark-up language in general and its link syntax in particular.

Insert example code

Adding a formatted code block:

 {{{
 def HelloWorld():
     print "Hello World"
 }}}

Inlining formatted code in text:

 The function `HelloWorld` prints "Hello World".

Refer to another ticket

 #1 or ticket:1

Refer to a Subversion revision (aka changeset)

 r1, [1] or changeset:1

There's much more information about Trac's mark-up language in general and its link syntax in particular.