diff --git a/docs/contributing.txt b/docs/contributing.txt index de9236f6c1..9300029f27 100644 --- a/docs/contributing.txt +++ b/docs/contributing.txt @@ -122,9 +122,9 @@ Patch style * Name the patch file with a ``.diff`` extension; this will let the ticket tracker apply correct syntax highlighting, which is quite helpful. - * Put the prefix "[patch] " before the title of your ticket. This will make - it obvious that the ticket includes a patch, and it will add the ticket - to the `list of tickets with patches`_. + * Check the "Has patch" box on the ticket details. This will make it + obvious that the ticket includes a patch, and it will add the ticket to + the `list of tickets with patches`_. * The code required to fix a problem or add a feature is an essential part of a patch, but it is not the only part. A good patch should also include @@ -151,24 +151,70 @@ Unfortunately, not all bug reports in the `ticket tracker`_ provide all the `required details`_. A number of tickets have patches, but those patches don't meet all the requirements of a `good patch`_. -One way to help out is to *triage* bugs that have been reported by other users. -Pick an open ticket that is missing some details, and try to replicate the -problem. Fill in the missing pieces of the report. If the ticket doesn't have -a patch, create one. +One way to help out is to *triage* bugs that have been reported by other +users. A couple of dedicated volunteers work on this regularly, but more help +is always appreciated. -Once you've completed all the missing details on the ticket and you have a -patch with all the required features, e-mail `django-developers`_. Indicate -that you have triaged a ticket, and recommend a course of action for dealing -with that ticket. +Most of the workflow is based around the concept of a ticket's "triage stage". +This stage describes where in its lifetime a given ticket is at any time. +Along with a handful of flags, this field easily tells us what and who each +ticket is waiting on. -At first, this may require you to be persistent. If you find that your triaged -ticket still isn't getting attention, occasional polite requests for eyeballs -to look at your ticket may be necessary. However, as you earn a reputation for -quality triage work, you should find that it is easier to get the developers' -attention. +Since a picture is worth a thousand words, let's start there: + +.. image:: http://media.djangoproject.com/img/doc/djangotickets.png + :height: 451 + :width: 590 + :alt: Django's ticket workflow + +We've got two roles here: + + * Core developers: people with commit access who make the decisions and + write the bulk of the code. + + * Ticket triagers: community members who keep track of tickets, making + sure the tickets are always categorized correctly. + +Second, note the four triage stages: + + 1. A ticket starts as "Unreviewed", meaning that a triager has yet to + examine the ticket and move it along. + + 2. "Design decision needed" means "this concept requires a design + decision," which should be discussed either in the ticket comments or on + django-developers. + + 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. + + 4. If a ticket has an associated patch (see below), a triager will review the + patch. If the patch is complete, it'll be marked as "ready for checkin" so + that a core developer knows to review and check in the patches. + +The second part of this workflow involves a set of flags the describe what the +ticket has or needs in order to be "ready for checkin": + + "Has patch" + The means the ticket has an associated patch_. These will be + reviewed to see if the patch is "good". + + "Needs documentation" + This flag is used for tickets with patches that need associated + documentation. Complete documentation of features is a prerequisite + before we can check a fix into the codebase. + + "Needs tests" + This flags the patch as needing associated unit tests. Again, this is a + required part of a valid patch. + + "Patch needs improvement" + This flag means that although the ticket *has* a patch, it's not quite + ready for checkin. This could mean the patch no longer applies + cleanly, or that the code doesn't live up to our standards. .. _required details: `Reporting bugs`_ .. _good patch: `Patch style`_ +.. _patch: `Submitting patches`_ Submitting and maintaining translations ======================================= @@ -548,7 +594,7 @@ requests for commit access are potential flame-war starters, and will be ignored .. _search the tracker: http://code.djangoproject.com/search .. _django-users: http://groups.google.com/group/django-users .. _`#django`: irc://irc.freenode.net/django -.. _list of tickets with patches: http://code.djangoproject.com/report/12 +.. _list of tickets with patches: http://code.djangoproject.com/query?status=new&status=assigned&status=reopened&has_patch=1&order=priority .. _PEP 8: http://www.python.org/peps/pep-0008.html .. _i18n documentation: http://www.djangoproject.com/documentation/i18n/ .. _i18n branch: http://code.djangoproject.com/browser/django/branches/i18n diff --git a/docs/testing.txt b/docs/testing.txt index 61b34e8c83..7618aaea66 100644 --- a/docs/testing.txt +++ b/docs/testing.txt @@ -244,11 +244,11 @@ can be invoked on the ``Client`` instance. ``login(path, username, password)`` In a production site, it is likely that some views will be protected with - the @login_required URL provided by ``django.contrib.auth``. Interacting + the @login_required decorator provided by ``django.contrib.auth``. Interacting with a URL that has been login protected is a slightly complex operation, - so the Test Client provides a simple URL to automate the login process. A + so the Test Client provides a simple method to automate the login process. A call to ``login()`` stimulates the series of GET and POST calls required - to log a user into a @login_required protected URL. + to log a user into a @login_required protected view. If login is possible, the final return value of ``login()`` is the response that is generated by issuing a GET request on the protected URL. If login