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 would like to see how Trac works, either download and install it locally, or check the unofficial ​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 mailing list or 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. Also 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 custom query, where you can easily filter tickets based on various criteria.

If you're Still Unsure

Well, create the new ticket anyway, but please observe the guidelines below.

How to Proceed?

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

Please follow these 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. A missing feature is an enhancement request, regardless of how important that feature is to you and 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, so that 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
    • for Trac itself, you should pick the appropriate version from the drop down list. If devel is chosen, which usually means you're using trunk​ or a 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 and 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 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 as hints for improving the ongoing development process of Trac itself!

— The TracTeam