per-object-permissions: Merged to trunk [5486] NOTE: Not fully tested, will be working on this over the next few weeks.

git-svn-id: http://code.djangoproject.com/svn/django/branches/per-object-permissions@5488 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 200 insertions, 27 deletions

diff --git a/docs/contributing.txt b/docs/contributing.txt
index de9236f6c1..31409f27bd 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,97 @@ 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"
+        This 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.
+
+A ticket can be resolved in a number of ways:
+
+    "fixed"
+        Used by one of the core developers once a patch has been rolled into
+        Django and the issue is fixed.
+
+    "invalid"
+        Used if the ticket is found to be incorrect or a user error.
+
+    "wontfix"
+        Used when a core developer decides that this request is not
+        appropriate for consideration in Django. This is usually chosen after
+        discussion in the ``django-developers`` mailing list, and you should
+        feel free to join in when it's something you care about.
+
+    "duplicate"
+        Used when another ticket covers the same issue. By closing duplicate
+        tickets, we keep all the discussion in one place, which helps everyone.
+
+    "worksforme"
+        Used when the triage team is unable to replicate the original bug.
+
+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 tell us why. Please do not
+reopen tickets that have been marked as "wontfix" by core developers.
 
 .. _required details: `Reporting bugs`_
 .. _good patch: `Patch style`_
+.. _patch: `Submitting patches`_
 
 Submitting and maintaining translations
 =======================================
@@ -186,7 +259,7 @@ translated, here's what to do:
       `i18n documentation`_.
 
 .. _Django i18n mailing list: http://groups.google.com/group/django-i18n/
-.. _i18n documentation: http://www.djangoproject.com/documentation/i18n/
+.. _i18n documentation: ../i18n/
 
 Coding style
 ============
@@ -206,6 +279,15 @@ Please follow these coding standards when writing code for inclusion in Django:
     * Mark all strings for internationalization; see the `i18n documentation`_
       for details.
 
+    * Please don't put your name in the code you contribute. Our policy is to
+      keep contributors' names in the ``AUTHORS`` file distributed with Django
+      -- not scattered throughout the codebase itself. Feel free to include a
+      change to the ``AUTHORS`` file in your patch if you make more than a
+      single trivial change.
+
+Template style
+--------------
+
     * In Django template code, put one (and only one) space between the curly
       brackets and the tag contents.
 
@@ -217,6 +299,9 @@ Please follow these coding standards when writing code for inclusion in Django:
 
           {{foo}}
 
+View style
+----------
+
     * In Django views, the first parameter in a view function should be called
       ``request``.
 
@@ -230,9 +315,72 @@ Please follow these coding standards when writing code for inclusion in Django:
           def my_view(req, foo):
               # ...
 
-    * Please don't put your name in the code. While we appreciate all
-      contributions to Django, our policy is not to publish individual
-      developer names in code -- for instance, at the top of Python modules.
+Model style
+-----------
+
+    * Field names should be all lowercase, using underscores instead of
+      camelCase.
+
+      Do this::
+
+          class Person(models.Model):
+              first_name = models.CharField(maxlength=20)
+              last_name = models.CharField(maxlength=40)
+
+      Don't do this::
+
+          class Person(models.Model):
+              FirstName = models.CharField(maxlength=20)
+              Last_Name = models.CharField(maxlength=40)
+
+    * The ``class Meta`` should appear *after* the fields are defined, with
+      a single blank line separating the fields and the class definition.
+
+      Do this::
+
+          class Person(models.Model):
+              first_name = models.CharField(maxlength=20)
+              last_name = models.CharField(maxlength=40)
+
+              class Meta:
+                  verbose_name_plural = 'people'
+
+      Don't do this::
+
+          class Person(models.Model):
+              first_name = models.CharField(maxlength=20)
+              last_name = models.CharField(maxlength=40)
+              class Meta:
+                  verbose_name_plural = 'people'
+
+      Don't do this, either::
+
+          class Person(models.Model):
+              class Meta:
+                  verbose_name_plural = 'people'
+
+              first_name = models.CharField(maxlength=20)
+              last_name = models.CharField(maxlength=40)
+
+    * The order of model inner classes and standard methods should be as
+      follows (noting that these are not all required):
+
+        * All database fields
+        * ``class Meta``
+        * ``class Admin``
+        * ``def __str__()``
+        * ``def save()``
+        * ``def get_absolute_url()``
+        * Any custom methods
+
+    * If ``choices`` is defined for a given model field, define the choices as
+      a tuple of tuples, with an all-uppercase name, either near the top of the
+      model module or just above the model class. Example::
+
+          GENDER_CHOICES = (
+              ('M', 'Male'),
+              ('F', 'Female'),
+          )
 
 Committing code
 ===============
@@ -311,7 +459,7 @@ The Django tests all use the testing infrastructure that ships with Django for
 testing applications. See `Testing Django applications`_ for an explanation of
 how to write new tests.
 
-.. _Testing Django applications: http://www.djangoproject.com/documentation/testing/
+.. _Testing Django applications: ../testing/
 
 Running the unit tests
 ----------------------
@@ -321,10 +469,11 @@ To run the tests, ``cd`` to the ``tests/`` directory and type::
     ./runtests.py --settings=path.to.django.settings
 
 Yes, the unit tests need a settings module, but only for database connection
-info -- the ``DATABASE_ENGINE``, ``DATABASE_USER`` and ``DATABASE_PASSWORD``.
-You will also need a ``ROOT_URLCONF`` setting (its value is ignored; it just
-needs to be present) and a ``SITE_ID`` setting (any integer value will do) in
-order for all the tests to pass.
+info -- the ``DATABASE_NAME`` (required, but will be ignored),
+``DATABASE_ENGINE``, ``DATABASE_USER`` and ``DATABASE_PASSWORD`` settings. You
+will also need a ``ROOT_URLCONF`` setting (its value is ignored; it just needs
+to be present) and a ``SITE_ID`` setting (any integer value will do) in order
+for all the tests to pass.
 
 The unit tests will not touch your existing databases; they create a new
 database, called ``django_test_db``, which is deleted when the tests are
@@ -438,6 +587,29 @@ Alternatively, you can use a symlink called ``django`` that points to the
 location of the branch's ``django`` package. If you want to switch back, just
 change the symlink to point to the old code.
 
+A third option is to use a `path file`_ (``<something>.pth``) which should
+work on all systems (including Windows, which doesn't have symlinks
+available). First, make sure there are no files, directories or symlinks named
+``django`` in your ``site-packages`` directory. Then create a text file named
+``django.pth`` and save it to your ``site-packages`` directory. That file
+should contain a path to your copy of Django on a single line and optional
+comments. Here is an example that points to multiple branches. Just uncomment
+the line for the branch you want to use ('Trunk' in this example) and make
+sure all other lines are commented::
+
+    # Trunk is a svn checkout of:
+    #   http://code.djangoproject.com/svn/django/trunk/
+    #
+    /path/to/trunk
+
+    # <branch> is a svn checkout of:
+    #   http://code.djangoproject.com/svn/django/branches/<branch>/
+    #
+    #/path/to/<branch>
+
+    # On windows a path may look like this:
+    # C:/path/to/<branch>
+
 If you're using Django 0.95 or earlier and installed it using
 ``python setup.py install``, you'll have a directory called something like
 ``Django-0.95-py2.4.egg`` instead of ``django``. In this case, edit the file
@@ -445,6 +617,8 @@ If you're using Django 0.95 or earlier and installed it using
 file. Then copy the branch's version of the ``django`` directory into
 ``site-packages``.
 
+.. _path file: http://docs.python.org/lib/module-site.html
+
 Official releases
 =================
 
@@ -548,8 +722,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
 .. _`tags/releases`: http://code.djangoproject.com/browser/django/tags/releases