= 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. Some issues have even been reported dozens of time, see our MostFrequentDuplicates tickets. 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 by you**//: - 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 //**should be left empty**//: - The '''Assign to''' person will be the developer taking responsibility for the ticket, or the patch contributor if the patch is good enough to be mostly applied as is - The '''Priority''' will be arbitrarily set by a Trac developer ;) - The '''Milestone''' will also be set by us **after** the [TracTicketTriage ticket triage]. So it's important to leave the milestone field ''empty'', which is used by us as an indicator that 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