[1.2.X] Fixed #14702 -- Added a "needsinfo" resolution to Trac, and added supporting documentation on the new resolution and closing tickets in general.

Backport of [15665] from trunk.

git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.2.X@15666 bcc190cf-cafb-0310-a4f2-bffc1f526a37

2 files changed, 65 insertions, 6 deletions

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 <ticket-resolutions>` 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 31774b4bdc..390ce544da 100644
--- a/docs/internals/contributing.txt
+++ b/docs/internals/contributing.txt
@@ -261,12 +261,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
@@ -275,16 +278,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
@@ -309,6 +312,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 <triage-stages-explained>` 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"
@@ -338,12 +352,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 <closing-tickets>`.
+
 .. _required details: `Reporting bugs`_
 .. _good patch: `Patch style`_
 .. _triage by the community: `Triage by the general community`_