Changes between Initial Version and Version 1 of TicketGuidelines


Ignore:
Timestamp:
Mar 4, 2010, 9:28:04 AM (5 years ago)
Author:
damato
Comment:

initial version

Legend:

Unmodified
Added
Removed
Modified
  • TicketGuidelines

    v1 v1  
     1= Ticket Guidelines =
     2[[TOC]]
     3
     4== Guidelines for Creating a New Ticket == #new-ticket-guidelines
     5You are about to file a new ticket. Please read this guidelines carefully.
     6
     7=== When Should I Create a New Ticket? ===
     8
     9==== Support and Installation Issues ====
     10Support questions should be asked using the [/contactform contact form], not filed as tickets. Be sure to review the [wiki:FAQ project's FAQ] first, as a lot of common issues are already covered there.
     11
     12==== Isn't There Already a Similar Ticket? ====
     13Please check whether the issue you've encountered has been reported before. You should definitively have a look at the [wiki:MostFrequentDuplicates] page.
     14
     15When you have an error message, it's a good idea to copy/paste it in the [/search?ticket=on search box here], enclosed in "..." (for an exact match).
     16
     17If 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 [/query custom query], where you can easily filter tickets based on various criteria.
     18
     19==== If you're Still Unsure... ====
     20Well, create the [/newticket new ticket], we won't bite you ;)
     21
     22=== Filing a new ticket === #filing-a-ticket
     23So 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.
     24
     25Please follow these guidelines:
     26 * Maybe not necessary to mention it, but anyway: please write your ticket description '''in English'''.
     27
     28 * You should provide your '''email address''' (will not be publicly visible) -  or [/register register] an account - so that we can ask for more details on the issue, if necessary.
     29
     30 * Provide a concise and precise '''Summary'''. As when you write an email, 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.
     31
     32 * 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, no matter how important that feature is to you (you can use the ''severity'' field for ranking that). If it's neither (for instance a problem with the projects website) use ''Other''.
     33
     34 * 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:
     35   - ''How To Reproduce'': describe what you were doing when the problem happened. Someone following those instructions should be able to reproduce the problem.
     36   - ''System Information'': list the software components involved with their version (e.g. the Operating System)
     37   - ''Stacktrace'': if you have one, append it at the end of the description, enclosed in a `{{{` ... `}}}` block (see [wiki:WikiFormatting#PreformattedText here]).
     38   - Please use the ''Preview'' button before finally filing the ticket. You may also want to have a look at the [wiki:WikiFormatting wiki formatting possibilities] that can be used in the description.
     39
     40 * The following ticket fields ''should be correctly set'' by you:
     41   - The '''Version''' of the software you were using. This can usually be seen in the ''About'' page/dialog.
     42   - The '''Component''' specifies the subsystem of Trac in which the error happened or where the enhancement should be made. If you're not sure please make a good guess.
     43   - The '''Severity''' is a rough estimation of the impact of the problem or the importance of the enhancement (see [#severity below] for more details).
     44 
     45 * The following ticket fields ''may be set'' by you (if you know what you're doing):
     46   - The '''Complexity''' of this issue. Should only be changed (from ''unknown'') if you can estimate the complexity. It may be set or changed by the development team when new insight into the issue exists.
     47   - '''Is Blocking'''/'''Depends On''' references to other tickets this ticket depends on or is blocking.
     48 
     49 * The following ticket fields ''should not be set/changed'' by you:
     50   - The '''Assign to''' person will be deduced from the choice of the ''component'' or by the development team.
     51   - The '''Priority''' should be left ''undecided'' until a developer will be arbitrarily set this ;)
     52   - The '''Milestone''' will be set by a developer when it's decided in which milestone this issue will be integrated. If a patch is attached to this ticket, the milestone will most likely be one of the next to be completed (depending on whether the ticket is an enhancement or defect).
     53   - The '''Keywords''' can contain a few important words about the issue. There are some conventions about the keywords themselves, see [#keywords below] for more details.
     54
     55Please take all these guidelines with a grain of salt, those are not strict rules, only hints for improving the ongoing development process!
     56
     57----
     58
     59== Modifying a ticket == #modifying-ticket-guidelines
     60There are no special restriction on adding a comment to an already existing ticket (although the comment must be related to the ticket).
     61
     62However, if you want modify the ticket in any other way (i.e. changing ticket fields) please follow these guidelines:
     63
     64 * If you want to change a ticket field please follow the [##filing-a-ticket "new ticket" guidelines] for ticket fields.
     65 * Don't change a ticket field without leaving a comment about this change (unless it's clear why you did the change). Note that you can't change the ticket's description. This can only be done by the project admins (see [#description below]).
     66 * In most cases you should not close any tickets - unless they're your own and you come to the conclusion that it's [#resolutions invalid].
     67 * And also, don't close or reopen a ticket without a reason.
     68 * See also [wiki:TracTickets#comments Changing and Commenting Tickets]
     69
     70Please take all these guidelines with a grain of salt, those are not strict rules, only hints for improving the ongoing development process!
     71
     72----
     73
     74== More detailed explanations ==
     75This section contains no more guidelines but more detailed explanations for some of the ticket fields. It's not directly necessary to read on but it won't hurt and may help you to file even "better" tickets.
     76
     77=== Ticket Fields Overview === #ticket-fields
     78A  ticket contains the following information attributes:
     79 
     80 * '''Reporter''' - The author of the ticket.
     81 * '''Assigned to/Owner''' - Principal person responsible for handling the issue.
     82
     83 * '''Summary''' - A brief description summarizing the problem or issue.
     84 * '''Description''' - The body of the ticket. A good description should be specific, descriptive and to the point. WikiFormatting can be used here.
     85
     86 * '''Type''' - The nature of the ticket.
     87 * '''Severity''' - The severity of this issue, ranging from ''trivial'' to ''blocker''.
     88 * '''Priority''' - Indicates how fast this ticket will (probably) be handled.
     89 * '''Component''' - The project module or subsystem this ticket concerns.
     90 * '''Version''' - Version of the project that this ticket pertains to.
     91 * '''Milestone''' - When this issue should be resolved at the latest. This value usually should only be set by the development team.
     92 * '''Complexity''' - indicates how complex it'll probably be to handle this issue
     93 * '''Is Blocking'''/'''Depends On''' - references to other tickets this ticket depends on or is blocking.
     94
     95 * '''Keywords''' - Keywords that a ticket is marked with.  Useful for searching and report generation.
     96 * '''Cc''' - A comma-separated list of other users or E-Mail addresses to notify. ''Note that this does not imply responsiblity or any other policy.''
     97 
     98 * '''Status''' - What is the current status? One of `new`, `assigned`, `accepted`, `closed` and `reopened`. Note that this status can't be set directly but is set implicetly (i.e. when a ticket is created it gets the status `new`; when a user accepts a ticket, it gets the status `accepted` and so on).
     99 * '''Resolution''' - Reason for why a ticket was closed. The resolutions are defined [#resolutions below].
     100
     101=== Ticket Description === #description
     102Only administrators can edit ticket descriptions.  They are only edited to fix formatting errors, not the actual content. Occasionally, we may also add editorial notes, in order to not spread misleading information,or to summarize the current status of a long running issue. In all cases, it should be quite clear from the formatting what's coming from the original author and what has been annotated afterwards.
     103
     104=== Severity === #severity
     105The '''Severity''' is a rough estimation of the impact of the problem or the importance of the enhancement. Each ticket is set to one of these values (where ''major'' is the default):
     106
     107||'''type'''  ||'''meaning for defects'''                               ||'''meaning for enhancements'''         ||
     108||''blocker'' ||basic functionality is not available until this is fixed||should ''not be used'' for enhancements||
     109||''critical''||severe loss of data due to the defect                   ||highly needed enhancement              ||
     110||''major''   ||defect with major impact                                ||big enhancement                        ||
     111||''minor''   ||defect with minor impact                                ||small enhancement                      ||
     112||''trivial'' ||defect with little or no impact                         ||cosmetic enhancement                   ||
     113
     114=== Keywords === #keywords
     115The purpose of keywords is to be able to generate pertinent and focused [TracQuery queries], so use them appropriately.
     116
     117 * General indications - influencing the ticket workflow
     118   - [query:group=status&keywords~=needinfo needinfo] -
     119     waiting on information from the reporter
     120   - [query:group=status&keywords~=verify verify] -
     121     the ticket looks to be a valid bug report, but it would be worth that someone actually reproduces it, mainly because the asignee can't reproduce it himself for some reason (different platform / browser / database, etc.)
     122   - [query:group=status&keywords~=consider consider] -
     123     interesting tickets, mainly for enhancements requests, that are worth to consider in the scope of a given milestone, but for which there's no commitment yet
     124   - [query:group=status&keywords~=helpwanted helpwanted] -
     125     tickets which are looking for contributors
     126   - [query:group=status&keywords~=review review] -
     127     review of the propose solution requested
     128   - [query:group=status&keywords~=patch patch] -
     129     a patch that handles the ticket is attached to it
     130
     131 * Platform specific issues:
     132   - [query:group=status&keywords~=windows windows]
     133   - [query:group=status&keywords~=solaris solaris]
     134   - [query:group=status&keywords~=linux linux]
     135   - [query:group=status&keywords~=macosx macosx]
     136
     137 * Other kinds of grouping
     138   * [query:group=status&keywords~=crash crash] -
     139     There's a segmentation fault or other serious OS level error implied.
     140   * [query:group=status&keywords~=memory memory] -
     141     Out of memory condition, most probably involving memory leaks.
     142   * [query:group=status&keywords~=security security] -
     143     Security issues
     144   * [query:group=status&keywords~=weird weird] -
     145     Bugs from outer space (things that never should have happend)
     146
     147== Resolutions == #resolutions
     148The reason for why a ticket was closed. These resolutions exist:
     149
     150 '''fixed''':: is used when the resolution of the ticket can be linked to some change in the repository, a code change, a primary documentation fix, a contribution script added, etc. For ticket type '''other''', fixed is used even if there was no trackable change in the repository/documentation.
     151 '''wontfix''':: the ''defect'' reported is not really out software's fault; the requested ''enhancement'' won't be implemented because we don't think it fits in the scope of our software and/or it can be obtained in a different way.
     152   * ''Note'': In some cases however, the issue may be left open even if the cause of the issue is not directly our software's fault, so that workarounds and user experience can be collected.
     153 '''invalid''':: the ''defect'' reported was not really a problem; the requested ''enhancement'' is already implemented.
     154 '''junk''':: the ticket was a test ticket, spam, etc.
     155 '''duplicate''':: there's already another ticket about the same issue
     156   * If marking as `duplicate`, include referring ticket #s in both duplicate ''and'' duplicated tickets.
     157     - In duplicate ticket: ''This ticket is duplicate of !#1234''
     158     - In original request: ''!#2345 has been marked as duplicate of this ticket''
     159   * We usually let open the ticket which contains the most up-to-the-point discussion about the issue, the one which contains an appropriate patch, or other than that, the oldest ticket.
     160   * Finally, if it's the n^th^ time such a duplicate has been created, it's about time to list it in the ticket duplicates hall of fame, i.e. the [wiki:MostFrequentDuplicates] page.