wiki:TicketGuidelines

Version 1 (modified by damato, 4 years ago) (diff)

initial version

Ticket Guidelines

Guidelines for Creating a New Ticket

You are about to file a new ticket. Please read this guidelines carefully.

When Should I Create a New Ticket?

Support and Installation Issues

Support questions should be asked using the contact form, not filed as tickets. Be sure to review the project's FAQ first, as a lot of common issues are already covered there.

Isn't There Already a Similar Ticket?

Please check whether the issue you've encountered has been reported before. You should definitively have a look at the MostFrequentDuplicates? page.

When you have an error message, it's a good idea to copy/paste it in the search box here, 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, we won't bite you ;)

Filing a new ticket

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 these guidelines:

  • Maybe not necessary to mention it, but anyway: please write your ticket description in English.
  • You should provide your email address (will not be publicly visible) - or register an account - so that we can ask for more details on the issue, if necessary.
  • 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.
  • 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.
  • 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 (e.g. the Operating System)
    • Stacktrace: if you have one, append it at the end of the description, enclosed in a {{{ ... }}} block (see here).
    • Please use the Preview button before finally filing the ticket. You may also want to have a look at the wiki formatting possibilities that can be used in the description.
  • The following ticket fields should be correctly set by you:
    • The Version of the software you were using. This can usually be seen in the About page/dialog.
    • 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.
    • The Severity is a rough estimation of the impact of the problem or the importance of the enhancement (see below for more details).

  • The following ticket fields may be set by you (if you know what you're doing):
    • 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.
    • Is Blocking/Depends On references to other tickets this ticket depends on or is blocking.

  • The following ticket fields should not be set/changed by you:
    • The Assign to person will be deduced from the choice of the component or by the development team.
    • The Priority should be left undecided until a developer will be arbitrarily set this ;)
    • 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).
    • The Keywords can contain a few important words about the issue. There are some conventions about the keywords themselves, see below for more details.

Please take all these guidelines with a grain of salt, those are not strict rules, only hints for improving the ongoing development process!


Modifying a ticket

There are no special restriction on adding a comment to an already existing ticket (although the comment must be related to the ticket).

However, if you want modify the ticket in any other way (i.e. changing ticket fields) please follow these guidelines:

  • If you want to change a ticket field please follow the "new ticket" guidelines for ticket fields.
  • 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 below).
  • In most cases you should not close any tickets - unless they're your own and you come to the conclusion that it's invalid.
  • And also, don't close or reopen a ticket without a reason.
  • See also Changing and Commenting Tickets

Please take all these guidelines with a grain of salt, those are not strict rules, only hints for improving the ongoing development process!


More detailed explanations

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

Ticket Fields Overview

A ticket contains the following information attributes:

  • Reporter - The author of the ticket.
  • Assigned to/Owner - Principal person responsible for handling the issue.
  • Summary - A brief description summarizing the problem or issue.
  • Description - The body of the ticket. A good description should be specific, descriptive and to the point. WikiFormatting can be used here.
  • Type - The nature of the ticket.
  • Severity - The severity of this issue, ranging from trivial to blocker.
  • Priority - Indicates how fast this ticket will (probably) be handled.
  • Component - The project module or subsystem this ticket concerns.
  • Version - Version of the project that this ticket pertains to.
  • Milestone - When this issue should be resolved at the latest. This value usually should only be set by the development team.
  • Complexity - indicates how complex it'll probably be to handle this issue
  • Is Blocking/Depends On - references to other tickets this ticket depends on or is blocking.
  • Keywords - Keywords that a ticket is marked with. Useful for searching and report generation.
  • 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.

  • 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).
  • Resolution - Reason for why a ticket was closed. The resolutions are defined below.

Ticket Description

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

Severity

The 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):

type meaning for defects meaning for enhancements
blocker basic functionality is not available until this is fixedshould not be used for enhancements
criticalsevere loss of data due to the defect highly needed enhancement
major defect with major impact big enhancement
minor defect with minor impact small enhancement
trivial defect with little or no impact cosmetic enhancement

Keywords

The purpose of keywords is to be able to generate pertinent and focused queries, so use them appropriately.

  • General indications - influencing the ticket workflow
    • needinfo - waiting on information from the reporter
    • verify - 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.)
    • consider - 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
    • helpwanted - tickets which are looking for contributors
    • review - review of the propose solution requested
    • patch - a patch that handles the ticket is attached to it
  • Other kinds of grouping
    • crash - There's a segmentation fault or other serious OS level error implied.
    • memory - Out of memory condition, most probably involving memory leaks.
    • security - Security issues
    • weird - Bugs from outer space (things that never should have happend)

Resolutions

The reason for why a ticket was closed. These resolutions exist:

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.
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.
  • 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.
invalid
the defect reported was not really a problem; the requested enhancement is already implemented.
junk
the ticket was a test ticket, spam, etc.
duplicate
there's already another ticket about the same issue
  • If marking as duplicate, include referring ticket #s in both duplicate and duplicated tickets.
    • In duplicate ticket: This ticket is duplicate of #1234
    • In original request: #2345 has been marked as duplicate of this ticket
  • 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.
  • Finally, if it's the nth time such a duplicate has been created, it's about time to list it in the ticket duplicates hall of fame, i.e. the MostFrequentDuplicates? page.