Commit f1dd46b6 authored by Gabriel Hurley's avatar Gabriel Hurley
Browse files

[1.2.X] Fixed #14702 -- Added a "needsinfo" resolution to Trac, and added... 

[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
parent a90e297f

docs/howto/contribute.txt

+35 −0
Original line number Diff line number Diff line
@@ -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

---------------------

docs/internals/contributing.txt

+30 −6
Original line number Diff line number Diff line
@@ -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`_