Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Fixed #14702 -- Added a "needsinfo" resolution to Trac, and added sup…

…porting documentation on the new resolution and closing tickets in general.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@15665 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 2b7b4683257c072f74b03358ccc368831b872671 1 parent 28123d7
Gabriel Hurley authored
Showing with 65 additions and 6 deletions.
  1. +35 −0 docs/howto/contribute.txt
  2. +30 −6 docs/internals/contributing.txt
35 docs/howto/contribute.txt
View
@@ -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
---------------------
36 docs/internals/contributing.txt
View
@@ -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 <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"
@@ -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 <closing-tickets>`.
+
.. _required details: `Reporting bugs`_
.. _good patch: `Patch style`_
.. _triage by the community: `Triage by the general community`_
Please sign in to comment.
Something went wrong with that request. Please try again.