= Guidelines for Creating a New Ticket =

You are about to file a ticket against Trac.

Please note that this is not a demo or test system. Rather, it is used for the development of Trac itself. If you'd like to see how Trac works, either [TracDownload download] and [TracInstall install] it locally, or check the unofficial [http://www.hosted-projects.com/trac/TracDemo/Demo demo site].

== When Should I Create a New Ticket? ==

Are you in charge of the Trac installation which displays a failure?
If not, you should probably first contact the local Trac administrator. 
He can then decide if the problem needs to be fixed locally or in Trac itself.

=== Support and Installation Issues ===

Support and installation questions should be asked on the [MailingList mailing list] or [IrcChannel IRC channel], not filed as tickets. Be sure to review the mailing list archives first, as a lot of common installation issues are already covered there.

=== Isn't There Already a Similar Ticket? ===

Please check whether the issue you've encountered has been reported before.
At the time of this writing, we have 732 duplicates on a total of 3928 valid tickets, so that's nearly one out of five tickets which shouldn't have been created in the first place.

When you have an error message, it's a good idea to copy/paste it in the search box, enclosed in "..." (for an exact match).

If not, pick a few keywords and do a search on them. If you have a more precise knowledge about the issue, you can try a [http://trac.edgewall.org/query custom query], where you can easily filter tickets based on various criteria.

=== If you're Still Unsure... ===

Well, create the new ticket anyway, we won't bite you ;)

== How to Proceed? ==

So the issue you want to report has not been addressed before, and you're confident it's about time to create a new ticket for it.

Please follow those guidelines:
 - Provide a concise and precise '''Summary'''. As when you write an e-mail, 
   the ticket's summary is the first thing people will see about this ticket, 
   in the timeline, reports and other places in Trac, so it's quite important to get it right. 
 - What's the appropriate Ticket '''Type'''? Is this a ''Defect'' report or an ''Enhancement'' request?
   A defect is an existing feature not working as advertised, 
   adding a missing feature is an enhancement request, however important that feature is to you 
   (you can use the ''severity'' field for ranking that).
 - The '''Description''' is the place where you give all the details about the issue. 
   Good descriptions for a problem report are the ones that make it easy for the developer 
   to understand and/or reproduce the problem. 
   To that end, it's usually necessary to give the following information:
   - ''How To Reproduce'': describe what you were doing when the problem happened. 
     Someone following those instructions should be able to reproduce the problem.
   - ''System Information'': list the software components involved with their version 
     - the Operating System
     - the Python version used
     - the database backend and their bindings if relevant
     - the versioning system and their bindings if relevant, etc.). 
     - for Trac itself, you should pick the appropriate ''version'' from the drop down list. 
       If `devel` is chosen (which usually means you're using [source:trunk] or a [source:sandbox branch], 
       you should additionally specify the branch used, and the precise revision number used).
       Also, if you're using a patched version, it's necessary to refer to the patches used.
   - ''Python backtrace'': if you have one, append it at the end of the description, 
     enclosed in a `{{{` ... `}}}` block.
 - The following ticket fields should be correctly set:
   - The '''Version''' of the Trac software you were using. This can usually be seen in the ''About'' page.
   - The '''Component''' specifies the subsystem of Trac in which the error happened or where the enhancement should be made
   - The '''Severity''' is a rough estimation of the impact of the problem or the importance of the enhancement
   - The '''Keywords''' can contain a few important words about the issue (though we tend to use some conventions about the keywords themselves, see TracTicketTriage#Keywords for more details).
 - The following ticket fields can be left as they are:
   - The '''Assign to''' person will be deduced from the choice of the ''component''
   - The '''Priority''' will be arbitrarily set by a Trac developer ;)
   - The '''Milestone''' will be set after the [TracTicketTriage ticket triage]. 
     An empty milestone means the ticket has not yet been triaged.

Please take all these guidelines with a grain of salt, those are not strict rules, only hints for improving the ongoing development process of Trac itself!

-- The TracTeam