diff options
Diffstat (limited to 'docs/contributing.txt')
| -rw-r--r-- | docs/contributing.txt | 227 |
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 |