| 1 | = Guidelines for Creating a New Ticket = |
| 2 | |
| 3 | You are about to file a ticket against Trac. |
| 4 | |
| 5 | 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]. |
| 6 | |
| 7 | == When Should I Create a New Ticket? == |
| 8 | |
| 9 | Are you in charge of the Trac installation which displays a failure? |
| 10 | If not, you should probably first contact the local Trac administrator. |
| 11 | He can then decide if the problem needs to be fixed locally or in Trac itself. |
| 12 | |
| 13 | === Support and Installation Issues === |
| 14 | |
| 15 | 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. |
| 16 | |
| 17 | === Isn't There Already a Similar Ticket? === |
| 18 | |
| 19 | Please check whether the issue you've encountered has been reported before. |
| 20 | 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. |
| 21 | |
| 22 | 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). |
| 23 | |
| 24 | 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. |
| 25 | |
| 26 | === If you're Still Unsure... === |
| 27 | |
| 28 | Well, create the new ticket anyway, we won't bite you ;) |
| 29 | |
| 30 | == How to Proceed? == |
| 31 | |
| 32 | 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. |
| 33 | |
| 34 | Please follow those guidelines: |
| 35 | - Provide a concise and precise '''Summary'''. As when you write an e-mail, |
| 36 | the ticket's summary is the first thing people will see about this ticket, |
| 37 | in the timeline, reports and other places in Trac, so it's quite important to get it right. |
| 38 | - What's the appropriate Ticket '''Type'''? Is this a ''Defect'' report or an ''Enhancement'' request? |
| 39 | A defect is an existing feature not working as advertised, |
| 40 | adding a missing feature is an enhancement request, however important that feature is to you |
| 41 | (you can use the ''severity'' field for ranking that). |
| 42 | - The '''Description''' is the place where you give all the details about the issue. |
| 43 | Good descriptions for a problem report are the ones that make it easy for the developer |
| 44 | to understand and/or reproduce the problem. |
| 45 | To that end, it's usually necessary to give the following information: |
| 46 | - ''How To Reproduce'': describe what you were doing when the problem happened. |
| 47 | Someone following those instructions should be able to reproduce the problem. |
| 48 | - ''System Information'': list the software components involved with their version |
| 49 | - the Operating System |
| 50 | - the Python version used |
| 51 | - the database backend and their bindings if relevant |
| 52 | - the versioning system and their bindings if relevant, etc.). |
| 53 | - for Trac itself, you should pick the appropriate ''version'' from the drop down list. |
| 54 | If `devel` is chosen (which usually means you're using [source:trunk] or a [source:sandbox branch], |
| 55 | you should additionally specify the branch used, and the precise revision number used). |
| 56 | Also, if you're using a patched version, it's necessary to refer to the patches used. |
| 57 | - ''Python backtrace'': if you have one, append it at the end of the description, |
| 58 | enclosed in a `{{{` ... `}}}` block. |
| 59 | - The following ticket fields should be correctly set: |
| 60 | - The '''Version''' of the Trac software you were using. This can usually be seen in the ''About'' page. |
| 61 | - The '''Component''' specifies the subsystem of Trac in which the error happened or where the enhancement should be made |
| 62 | - The '''Severity''' is a rough estimation of the impact of the problem or the importance of the enhancement |
| 63 | - 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). |
| 64 | - The following ticket fields can be left as they are: |
| 65 | - The '''Assign to''' person will be deduced from the choice of the ''component'' |
| 66 | - The '''Priority''' will be arbitrarily set by a Trac developer ;) |
| 67 | - The '''Milestone''' will be set after the [TracTicketTriage ticket triage]. |
| 68 | An empty milestone means the ticket has not yet been triaged. |
| 69 | |
| 70 | 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! |
| 71 | |
| 72 | -- The TracTeam |