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