diff --git a/docs/howto/contribute.txt b/docs/howto/contribute.txt index eb1dd105cc..286c9282c7 100644 --- a/docs/howto/contribute.txt +++ b/docs/howto/contribute.txt @@ -64,6 +64,8 @@ However, Trac can be quite confusing even to veteran contributors. Having to look at both flags and triage stages isn't immediately obvious, and the stages themselves can be misinterpreted. +.. _triage-stages-explained: + What Django's triage stages "really mean" ----------------------------------------- @@ -135,6 +137,39 @@ will eventually be merged to trunk. Tickets in this stage generally don't need further work. This may happen in the case of major features/refactors in each release cycle, or as part of the annual Google Summer of Code efforts. +.. _closing-tickets: + +Closing Tickets +--------------- + +When a ticket has completed its useful lifecycle, it's time for it to be closed. +Closing a ticket is a big responsibility, though. You have to be sure that +the issue is really resolved, and you need to keep in mind that the reporter +of the ticket may not be happy to have their ticket closed (unless it's fixed, +of course). If you're not certain about closing a ticket, just leave a comment +with your thoughts instead. + +If you do close a ticket, you should always make sure of the following: + + * Be certain that the issue is resolved. + + * Leave a comment explaining the decision to close the ticket. + + * If there is a way they can improve the ticket to reopen it, let them know. + + * If the ticket is a duplicate, reference the original ticket. + + * **Be polite.** No one likes having their ticket closed. It can be + frustrating or even discouraging. The best way to avoid turning people + off from contributing to Django is to be polite and friendly and to offer + suggestions for how they could improve this ticket and other tickets in the + future. + +.. seealso:: + + The :ref:`contributing reference ` contains a + description of each of the available resolutions in Trac. + Example Trac workflow --------------------- diff --git a/docs/internals/contributing.txt b/docs/internals/contributing.txt index 3c271d64e6..6e40b1f3b1 100644 --- a/docs/internals/contributing.txt +++ b/docs/internals/contributing.txt @@ -276,12 +276,15 @@ We've got two roles in this diagram: Django is a community project, and we encourage `triage by the community`_. +Triage stages +------------- + Second, note the five triage stages: - 1. A ticket starts as "Unreviewed", meaning that nobody has examined + 1. A ticket starts as **Unreviewed**, meaning that nobody has examined the ticket. - 2. "Design decision needed" means "this concept requires a design + 2. **Design decision needed** means "this concept requires a design decision," which should be discussed either in the ticket comments or on `django-developers`_. The "Design decision needed" step will generally only be used for feature requests. It can also be used for issues @@ -290,16 +293,16 @@ Second, note the five triage stages: standard) skip this step and move straight to "Accepted". 3. Once a ticket is ruled to be approved for fixing, it's moved into the - "Accepted" stage. This stage is where all the real work gets done. + **Accepted** stage. This stage is where all the real work gets done. - 4. In some cases, a ticket might get moved to the "Someday/Maybe" state. + 4. In some cases, a ticket might get moved to the **Someday/Maybe** state. This means the ticket is an enhancement request that we might consider adding to the framework if an excellent patch is submitted. These tickets are not a high priority. 5. If a ticket has an associated patch (see below), it will be reviewed - by the community. If the patch is complete, it'll be marked as "ready - for checkin" so that a core developer knows to review and commit the + by the community. If the patch is complete, it'll be marked as **Ready + for checkin** so that a core developer knows to review and commit the patch. The second part of this workflow involves a set of flags the describe what the @@ -324,6 +327,17 @@ ticket has or needs in order to be "ready for checkin": cleanly, there is a flaw in the implementation, or that the code doesn't meet our standards. +.. seealso:: + + The :ref:`contributing howto guide ` has a detailed + explanation of each of the triage stages and how the triage process works in + Trac. + +.. _ticket-resolutions: + +Ticket Resolutions +------------------ + A ticket can be resolved in a number of ways: "fixed" @@ -353,12 +367,22 @@ A ticket can be resolved in a number of ways: Used when the ticket doesn't contain enough detail to replicate the original bug. + "needsinfo" + Used when the ticket does not contain enough information to replicate + the reported issue but is potentially still valid. The ticket + should be reopened when more information is supplied. + If you believe that the ticket was closed in error -- because you're still having the issue, or it's popped up somewhere else, or the triagers have made a mistake -- please reopen the ticket and provide further information. Please do not reopen tickets that have been marked as "wontfix" by core developers. +.. seealso:: + + For more information on what to do when closing a ticket, please see the + :ref:`contributing howto guide `. + .. _required details: `Reporting bugs`_ .. _good patch: `Patch style`_ .. _triage by the community: `Triage by the general community`_