--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/parts/django/docs/internals/contributing.txt Sat Jan 08 11:20:57 2011 +0530
@@ -0,0 +1,1294 @@
+======================
+Contributing to Django
+======================
+
+If you think working *with* Django is fun, wait until you start working *on* it.
+We're passionate about helping Django users make the jump to contributing members
+of the community, so there are many ways you can help Django's development:
+
+ * Blog about Django. We syndicate all the Django blogs we know about on
+ the `community page`_; contact jacob@jacobian.org if you've got a blog
+ you'd like to see on that page.
+
+ * Report bugs and request features in our `ticket tracker`_. Please read
+ `Reporting bugs`_, below, for the details on how we like our bug reports
+ served up.
+
+ * Submit patches for new and/or fixed behavior. Please read `Submitting
+ patches`_, below, for details on how to submit a patch. If you're looking
+ for an easy way to start contributing to Django have a look at the
+ `easy-pickings`_ tickets.
+
+ * Join the `django-developers`_ mailing list and share your ideas for how
+ to improve Django. We're always open to suggestions, although we're
+ likely to be skeptical of large-scale suggestions without some code to
+ back it up.
+
+ * Triage patches that have been submitted by other users. Please read
+ `Ticket triage`_ below, for details on the triage process.
+
+That's all you need to know if you'd like to join the Django development
+community. The rest of this document describes the details of how our community
+works and how it handles bugs, mailing lists, and all the other minutiae of
+Django development.
+
+.. _reporting-bugs:
+
+Reporting bugs
+==============
+
+Well-written bug reports are *incredibly* helpful. However, there's a certain
+amount of overhead involved in working with any bug tracking system, so your
+help in keeping our ticket tracker as useful as possible is appreciated. In
+particular:
+
+ * **Do** read the :doc:`FAQ </faq/index>` to see if your issue might be a well-known question.
+
+ * **Do** `search the tracker`_ to see if your issue has already been filed.
+
+ * **Do** ask on `django-users`_ *first* if you're not sure if what you're
+ seeing is a bug.
+
+ * **Do** write complete, reproducible, specific bug reports. Include as
+ much information as you possibly can, complete with code snippets, test
+ cases, etc. This means including a clear, concise description of the
+ problem, and a clear set of instructions for replicating the problem.
+ A minimal example that illustrates the bug in a nice small test case
+ is the best possible bug report.
+
+ * **Don't** use the ticket system to ask support questions. Use the
+ `django-users`_ list, or the `#django`_ IRC channel for that.
+
+ * **Don't** use the ticket system to make large-scale feature requests.
+ We like to discuss any big changes to Django's core on the `django-developers`_
+ list before actually working on them.
+
+ * **Don't** reopen issues that have been marked "wontfix". This mark means
+ that the decision has been made that we can't or won't fix this particular
+ issue. If you're not sure why, please ask on `django-developers`_.
+
+ * **Don't** use the ticket tracker for lengthy discussions, because they're
+ likely to get lost. If a particular ticket is controversial, please move
+ discussion to `django-developers`_.
+
+ * **Don't** post to django-developers just to announce that you have filed
+ a bug report. All the tickets are mailed to another list
+ (`django-updates`_), which is tracked by developers and triagers, so we
+ see them as they are filed.
+
+.. _django-updates: http://groups.google.com/group/django-updates
+
+.. _reporting-security-issues:
+
+Reporting security issues
+=========================
+
+Report security issues to security@djangoproject.com. This is a private list
+only open to long-time, highly trusted Django developers, and its archives are
+not publicly readable.
+
+In the event of a confirmed vulnerability in Django itself, we will take the
+following actions:
+
+ * Acknowledge to the reporter that we've received the report and that a fix
+ is forthcoming. We'll give a rough timeline and ask the reporter to keep
+ the issue confidential until we announce it.
+
+ * Halt all other development as long as is needed to develop a fix, including
+ patches against the current and two previous releases.
+
+ * Determine a go-public date for announcing the vulnerability and the fix.
+ To try to mitigate a possible "arms race" between those applying the patch
+ and those trying to exploit the hole, we will not announce security
+ problems immediately.
+
+ * Pre-notify everyone we know to be running the affected version(s) of
+ Django. We will send these notifications through private e-mail which will
+ include documentation of the vulnerability, links to the relevant patch(es),
+ and a request to keep the vulnerability confidential until the official
+ go-public date.
+
+ * Publicly announce the vulnerability and the fix on the pre-determined
+ go-public date. This will probably mean a new release of Django, but
+ in some cases it may simply be patches against current releases.
+
+Submitting patches
+==================
+
+We're always grateful for patches to Django's code. Indeed, bug reports with
+associated patches will get fixed *far* more quickly than those without patches.
+
+"Claiming" tickets
+------------------
+
+In an open-source project with hundreds of contributors around the world, it's
+important to manage communication efficiently so that work doesn't get
+duplicated and contributors can be as effective as possible. Hence, our policy
+is for contributors to "claim" tickets in order to let other developers know
+that a particular bug or feature is being worked on.
+
+If you have identified a contribution you want to make and you're capable of
+fixing it (as measured by your coding ability, knowledge of Django internals
+and time availability), claim it by following these steps:
+
+ * `Create an account`_ to use in our ticket system.
+ * If a ticket for this issue doesn't exist yet, create one in our
+ `ticket tracker`_.
+ * If a ticket for this issue already exists, make sure nobody else has
+ claimed it. To do this, look at the "Assigned to" section of the ticket.
+ If it's assigned to "nobody," then it's available to be claimed.
+ Otherwise, somebody else is working on this ticket, and you either find
+ another bug/feature to work on, or contact the developer working on the
+ ticket to offer your help.
+ * Log into your account, if you haven't already, by clicking "Login" in the
+ upper right of the ticket page.
+ * Claim the ticket by clicking the radio button next to "Accept ticket"
+ near the bottom of the page, then clicking "Submit changes."
+
+If you have an account but have forgotten your password, you can reset it
+using the `password reset page`_.
+
+.. _Create an account: http://www.djangoproject.com/accounts/register/
+.. _password reset page: http://www.djangoproject.com/accounts/password/reset/
+
+Ticket claimers' responsibility
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Once you've claimed a ticket, you have a responsibility to work on that ticket
+in a reasonably timely fashion. If you don't have time to work on it, either
+unclaim it or don't claim it in the first place!
+
+Ticket triagers go through the list of claimed tickets from time to
+time, checking whether any progress has been made. If there's no sign of
+progress on a particular claimed ticket for a week or two, a triager may ask
+you to relinquish the ticket claim so that it's no longer monopolized and
+somebody else can claim it.
+
+If you've claimed a ticket and it's taking a long time (days or weeks) to code,
+keep everybody updated by posting comments on the ticket. If you don't provide
+regular updates, and you don't respond to a request for a progress report,
+your claim on the ticket may be revoked. As always, more communication is
+better than less communication!
+
+Which tickets should be claimed?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Of course, going through the steps of claiming tickets is overkill in some
+cases. In the case of small changes, such as typos in the documentation or
+small bugs that will only take a few minutes to fix, you don't need to jump
+through the hoops of claiming tickets. Just submit your patch and be done with
+it.
+
+Patch style
+-----------
+
+ * Make sure your code matches our `coding style`_.
+
+ * Submit patches in the format returned by the ``svn diff`` command.
+ An exception is for code changes that are described more clearly in plain
+ English than in code. Indentation is the most common example; it's hard to
+ read patches when the only difference in code is that it's indented.
+
+ Patches in ``git diff`` format are also acceptable.
+
+ * When creating patches, always run ``svn diff`` from the top-level
+ ``trunk`` directory -- i.e., the one that contains ``django``, ``docs``,
+ ``tests``, ``AUTHORS``, etc. This makes it easy for other people to apply
+ your patches.
+
+ * Attach patches to a ticket in the `ticket tracker`_, using the "attach file"
+ button. Please *don't* put the patch in the ticket description or comment
+ unless it's a single line patch.
+
+ * Name the patch file with a ``.diff`` extension; this will let the ticket
+ tracker apply correct syntax highlighting, which is quite helpful.
+
+ * 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
+ a regression test to validate the behavior that has been fixed (and prevent
+ the problem from arising again).
+
+ * If the code associated with a patch adds a new feature, or modifies behavior
+ of an existing feature, the patch should also contain documentation.
+
+Non-trivial patches
+-------------------
+
+A "non-trivial" patch is one that is more than a simple bug fix. It's a patch
+that introduces Django functionality and makes some sort of design decision.
+
+If you provide a non-trivial patch, include evidence that alternatives have
+been discussed on `django-developers`_. If you're not sure whether your patch
+should be considered non-trivial, just ask.
+
+Ticket triage
+=============
+
+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. A couple of dedicated volunteers work on this regularly, but more help
+is always appreciated.
+
+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.
+
+Since a picture is worth a thousand words, let's start there:
+
+.. image:: _images/djangotickets.png
+ :height: 451
+ :width: 590
+ :alt: Django's ticket workflow
+
+We've got two official roles here:
+
+ * Core developers: people with commit access who make the big decisions
+ and write the bulk of the code.
+
+ * Ticket triagers: trusted community members with a proven history of
+ working with the Django community. As a result of this history, they
+ have been entrusted by the core developers to make some of the smaller
+ decisions about tickets.
+
+Second, note the five triage stages:
+
+ 1. A ticket starts as "Unreviewed", meaning that nobody has examined
+ the ticket.
+
+ 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
+ that *might* be bugs, depending on opinion or interpretation. Obvious
+ bugs (such as crashes, incorrect query results, or non-compliance with a
+ 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.
+
+ 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), 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 by the triage team 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. This means that the
+ issue in the ticket is actually the result of a user error, or
+ describes a problem with something other than Django, or isn't
+ a bug report or feature request at all (for example, some new users
+ submit support queries as tickets).
+
+ "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 ticket doesn't contain enough detail 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`_
+
+Triage by the general community
+-------------------------------
+
+Although the core developers and ticket triagers make the big decisions in
+the ticket triage process, there's also a lot that general community
+members can do to help the triage process. In particular, you can help out by:
+
+ * Closing "Unreviewed" tickets as "invalid", "worksforme" or "duplicate."
+
+ * Promoting "Unreviewed" tickets to "Design decision needed" if a design
+ decision needs to be made, or "Accepted" in case of obvious bugs.
+
+ * Correcting the "Needs tests", "Needs documentation", or "Has patch" flags
+ for tickets where they are incorrectly set.
+
+ * Adding the `easy-pickings`_ keyword to tickets that are small and
+ relatively straightforward.
+
+ * Checking that old tickets are still valid. If a ticket hasn't seen
+ any activity in a long time, it's possible that the problem has been
+ fixed but the ticket hasn't yet been closed.
+
+ * Contacting the owners of tickets that have been claimed but have not seen
+ any recent activity. If the owner doesn't respond after a week or so,
+ remove the owner's claim on the ticket.
+
+ * Identifying trends and themes in the tickets. If there a lot of bug reports
+ about a particular part of Django, it may indicate we should consider
+ refactoring that part of the code. If a trend is emerging, you should
+ raise it for discussion (referencing the relevant tickets) on
+ `django-developers`_.
+
+However, we do ask the following of all general community members working in
+the ticket database:
+
+ * Please **don't** close tickets as "wontfix." The core developers will
+ make the final determination of the fate of a ticket, usually after
+ consultation with the community.
+
+ * Please **don't** promote tickets to "Ready for checkin" unless they are
+ *trivial* changes -- for example, spelling mistakes or broken links in
+ documentation.
+
+ * Please **don't** reverse a decision that has been made by a core
+ developer. If you disagree with a discussion that has been made,
+ please post a message to `django-developers`_.
+
+ * Please be conservative in your actions. If you're unsure if you should
+ be making a change, don't make the change -- leave a comment with your
+ concerns on the ticket, or post a message to `django-developers`_.
+
+.. _contributing-translations:
+
+Submitting and maintaining translations
+=======================================
+
+Various parts of Django, such as the admin site and validation error messages,
+are internationalized. This means they display different text depending on a
+user's language setting. For this, Django uses the same internationalization
+infrastructure available to Django applications described in the
+:doc:`i18n documentation</topics/i18n/index>`.
+
+These translations are contributed by Django users worldwide. If you find an
+incorrect translation, or if you'd like to add a language that isn't yet
+translated, here's what to do:
+
+ * Join the `Django i18n mailing list`_ and introduce yourself.
+
+ * Make sure you read the notes about :ref:`specialties-of-django-i18n`.
+
+ * Create translations using the methods described in the
+ :doc:`localization documentation </topics/i18n/localization>`. For this
+ you will use the ``django-admin.py makemessages`` tool. In this
+ particular case it should be run from the top-level ``django`` directory
+ of the Django source tree.
+
+ The script runs over the entire Django source tree and pulls out all
+ strings marked for translation. It creates (or updates) a message file in
+ the directory ``conf/locale`` (for example for ``pt_BR``, the file will be
+ ``conf/locale/pt_BR/LC_MESSAGES/django.po``).
+
+ * Make sure that ``django-admin.py compilemessages -l <lang>`` runs without
+ producing any warnings.
+
+ * Repeat the last two steps for the ``djangojs`` domain (by appending the
+ ``-d djangojs`` command line option to the ``django-admin.py``
+ invocations).
+
+ * Optionally, review and update the ``conf/locale/<locale>/formats.py``
+ file to describe the date, time and numbers formatting particularities of
+ your locale. See :ref:`format-localization` for details.
+
+ * Create a diff against the current Subversion trunk.
+
+ * Open a ticket in Django's ticket system, set its ``Component`` field to
+ ``Translations``, and attach the patch to it.
+
+.. _Django i18n mailing list: http://groups.google.com/group/django-i18n/
+
+Submitting javascript patches
+=============================
+
+.. versionadded:: 1.2
+
+Django's admin system leverages the jQuery framework to increase the
+capabilities of the admin interface. In conjunction, there is an emphasis on
+admin javascript performance and minimizing overall admin media file size.
+Serving compressed or "minified" versions of javascript files is considered
+best practice in this regard.
+
+To that end, patches for javascript files should include both the original
+code for future development (e.g. "foo.js"), and a compressed version for
+production use (e.g. "foo.min.js"). Any links to the file in the codebase
+should point to the compressed version.
+
+To simplify the process of providing optimized javascript code, Django
+includes a handy script which should be used to create a "minified" version.
+This script is located at ``/contrib/admin/media/js/compress.py``.
+
+Behind the scenes, ``compress.py`` is a front-end for Google's
+`Closure Compiler`_ which is written in Java. However, the Closure Compiler
+library is not bundled with Django directly, so those wishing to contribute
+complete javascript patches will need to download and install the library
+independently.
+
+The Closure Compiler library requires Java version 6 or higher (Java 1.6 or
+higher on Mac OS X). Note that Mac OS X 10.5 and earlier did not ship with Java
+1.6 by default, so it may be necessary to upgrade your Java installation before
+the tool will be functional. Also note that even after upgrading Java, the
+default `/usr/bin/java` command may remain linked to the previous Java
+binary, so relinking that command may be necessary as well.
+
+Please don't forget to run ``compress.py`` and include the ``diff`` of the
+minified scripts when submitting patches for Django's javascript.
+
+.. _Closure Compiler: http://code.google.com/closure/compiler/
+
+Django conventions
+==================
+
+Various Django-specific code issues are detailed in this section.
+
+Use of ``django.conf.settings``
+-------------------------------
+
+Modules should not in general use settings stored in ``django.conf.settings`` at
+the top level (i.e. evaluated when the module is imported). The explanation for
+this is as follows:
+
+Manual configuration of settings (i.e. not relying on the
+``DJANGO_SETTINGS_MODULE`` environment variable) is allowed and possible as
+follows::
+
+ from django.conf import settings
+
+ settings.configure({}, SOME_SETTING='foo')
+
+However, if any setting is accessed before the ``settings.configure`` line, this
+will not work. (Internally, ``settings`` is a ``LazyObject`` which configures
+itself automatically when the settings are accessed if it has not already been
+configured).
+
+So, if there is a module containing some code as follows::
+
+ from django.conf import settings
+ from django.core.urlresolvers import get_callable
+
+ default_foo_view = get_callable(settings.FOO_VIEW)
+
+...then importing this module will cause the settings object to be configured.
+That means that the ability for third parties to import the module at the top
+level is incompatible with the ability to configure the settings object
+manually, or makes it very difficult in some circumstances.
+
+Instead of the above code, a level of laziness or indirection must be used, such
+as :class:`django.utils.functional.LazyObject`, :func:`django.utils.functional.lazy` or
+``lambda``.
+
+Coding style
+============
+
+Please follow these coding standards when writing code for inclusion in Django:
+
+ * Unless otherwise specified, follow :pep:`8`.
+
+ You could use a tool like `pep8.py`_ to check for some problems in this
+ area, but remember that PEP 8 is only a guide, so respect the style of
+ the surrounding code as a primary goal.
+
+ * Use four spaces for indentation.
+
+ * Use underscores, not camelCase, for variable, function and method names
+ (i.e. ``poll.get_unique_voters()``, not ``poll.getUniqueVoters``).
+
+ * Use ``InitialCaps`` for class names (or for factory functions that
+ return classes).
+
+ * Mark all strings for internationalization; see the :doc:`i18n
+ documentation </topics/i18n/index>` for details.
+
+ * In docstrings, use "action words" such as::
+
+ def foo():
+ """
+ Calculates something and returns the result.
+ """
+ pass
+
+ Here's an example of what not to do::
+
+ def foo():
+ """
+ Calculate something and return the result.
+ """
+ pass
+
+ * 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.
+
+ Do this:
+
+ .. code-block:: html+django
+
+ {{ foo }}
+
+ Don't do this:
+
+ .. code-block:: html+django
+
+ {{foo}}
+
+View style
+----------
+
+ * In Django views, the first parameter in a view function should be called
+ ``request``.
+
+ Do this::
+
+ def my_view(request, foo):
+ # ...
+
+ Don't do this::
+
+ def my_view(req, foo):
+ # ...
+
+Model style
+-----------
+
+ * Field names should be all lowercase, using underscores instead of
+ camelCase.
+
+ Do this::
+
+ class Person(models.Model):
+ first_name = models.CharField(max_length=20)
+ last_name = models.CharField(max_length=40)
+
+ Don't do this::
+
+ class Person(models.Model):
+ FirstName = models.CharField(max_length=20)
+ Last_Name = models.CharField(max_length=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(max_length=20)
+ last_name = models.CharField(max_length=40)
+
+ class Meta:
+ verbose_name_plural = 'people'
+
+ Don't do this::
+
+ class Person(models.Model):
+ first_name = models.CharField(max_length=20)
+ last_name = models.CharField(max_length=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(max_length=20)
+ last_name = models.CharField(max_length=40)
+
+ * The order of model inner classes and standard methods should be as
+ follows (noting that these are not all required):
+
+ * All database fields
+ * Custom manager attributes
+ * ``class Meta``
+ * ``def __unicode__()``
+ * ``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'),
+ )
+
+Documentation style
+===================
+
+We place a high importance on consistency and readability of documentation.
+(After all, Django was created in a journalism environment!)
+
+How to document new features
+----------------------------
+
+We treat our documentation like we treat our code: we aim to improve it as
+often as possible. This section explains how writers can craft their
+documentation changes in the most useful and least error-prone ways.
+
+Documentation changes come in two forms:
+
+ * General improvements -- Typo corrections, error fixes and better
+ explanations through clearer writing and more examples.
+
+ * New features -- Documentation of features that have been added to the
+ framework since the last release.
+
+Our policy is:
+
+ **All documentation of new features should be written in a way that clearly
+ designates the features are only available in the Django development
+ version. Assume documentation readers are using the latest release, not the
+ development version.**
+
+Our preferred way for marking new features is by prefacing the features'
+documentation with: ".. versionadded:: X.Y", followed by an optional one line
+comment and a mandatory blank line.
+
+General improvements, or other changes to the APIs that should be emphasized
+should use the ".. versionchanged:: X.Y" directive (with the same format as the
+``versionadded`` mentioned above.
+
+There's a full page of information about the :doc:`Django documentation
+system </internals/documentation>` that you should read prior to working on the
+documentation.
+
+Guidelines for reST files
+-------------------------
+
+These guidelines regulate the format of our reST documentation:
+
+ * In section titles, capitalize only initial words and proper nouns.
+
+ * Wrap the documentation at 80 characters wide, unless a code example
+ is significantly less readable when split over two lines, or for another
+ good reason.
+
+Commonly used terms
+-------------------
+
+Here are some style guidelines on commonly used terms throughout the
+documentation:
+
+ * **Django** -- when referring to the framework, capitalize Django. It is
+ lowercase only in Python code and in the djangoproject.com logo.
+
+ * **e-mail** -- it has a hyphen.
+
+ * **MySQL**
+
+ * **PostgreSQL**
+
+ * **Python** -- when referring to the language, capitalize Python.
+
+ * **realize**, **customize**, **initialize**, etc. -- use the American
+ "ize" suffix, not "ise."
+
+ * **SQLite**
+
+ * **subclass** -- it's a single word without a hyphen, both as a verb
+ ("subclass that model") and as a noun ("create a subclass").
+
+ * **Web**, **World Wide Web**, **the Web** -- note Web is always
+ capitalized when referring to the World Wide Web.
+
+ * **Web site** -- use two words, with Web capitalized.
+
+Django-specific terminology
+---------------------------
+
+ * **model** -- it's not capitalized.
+
+ * **template** -- it's not capitalized.
+
+ * **URLconf** -- use three capitalized letters, with no space before
+ "conf."
+
+ * **view** -- it's not capitalized.
+
+Committing code
+===============
+
+Please follow these guidelines when committing code to Django's Subversion
+repository:
+
+ * For any medium-to-big changes, where "medium-to-big" is according to your
+ judgment, please bring things up on the `django-developers`_ mailing list
+ before making the change.
+
+ If you bring something up on `django-developers`_ and nobody responds,
+ please don't take that to mean your idea is great and should be
+ implemented immediately because nobody contested it. Django's lead
+ developers don't have a lot of time to read mailing-list discussions
+ immediately, so you may have to wait a couple of days before getting a
+ response.
+
+ * Write detailed commit messages in the past tense, not present tense.
+
+ * Good: "Fixed Unicode bug in RSS API."
+ * Bad: "Fixes Unicode bug in RSS API."
+ * Bad: "Fixing Unicode bug in RSS API."
+
+ * For commits to a branch, prefix the commit message with the branch name.
+ For example: "magic-removal: Added support for mind reading."
+
+ * Limit commits to the most granular change that makes sense. This means,
+ use frequent small commits rather than infrequent large commits. For
+ example, if implementing feature X requires a small change to library Y,
+ first commit the change to library Y, then commit feature X in a separate
+ commit. This goes a *long way* in helping all core Django developers
+ follow your changes.
+
+ * Separate bug fixes from feature changes.
+
+ Bug fixes need to be added to the current bugfix branch (e.g. the
+ ``1.0.X`` branch) as well as the current trunk.
+
+ * If your commit closes a ticket in the Django `ticket tracker`_, begin
+ your commit message with the text "Fixed #abc", where "abc" is the number
+ of the ticket your commit fixes. Example: "Fixed #123 -- Added support
+ for foo". We've rigged Subversion and Trac so that any commit message
+ in that format will automatically close the referenced ticket and post a
+ comment to it with the full commit message.
+
+ If your commit closes a ticket and is in a branch, use the branch name
+ first, then the "Fixed #abc." For example:
+ "magic-removal: Fixed #123 -- Added whizbang feature."
+
+ For the curious: We're using a `Trac post-commit hook`_ for this.
+
+ .. _Trac post-commit hook: http://trac.edgewall.org/browser/trunk/contrib/trac-post-commit-hook
+
+ * If your commit references a ticket in the Django `ticket tracker`_ but
+ does *not* close the ticket, include the phrase "Refs #abc", where "abc"
+ is the number of the ticket your commit references. We've rigged
+ Subversion and Trac so that any commit message in that format will
+ automatically post a comment to the appropriate ticket.
+
+Reverting commits
+-----------------
+
+Nobody's perfect; mistakes will be committed. When a mistaken commit is
+discovered, please follow these guidelines:
+
+ * Try very hard to ensure that mistakes don't happen. Just because we
+ have a reversion policy doesn't relax your responsibility to aim for
+ the highest quality possible. Really: double-check your work before
+ you commit it in the first place!
+
+ * If possible, have the original author revert his/her own commit.
+
+ * Don't revert another author's changes without permission from the
+ original author.
+
+ * If the original author can't be reached (within a reasonable amount
+ of time -- a day or so) and the problem is severe -- crashing bug,
+ major test failures, etc -- then ask for objections on django-dev
+ then revert if there are none.
+
+ * If the problem is small (a feature commit after feature freeze,
+ say), wait it out.
+
+ * If there's a disagreement between the committer and the
+ reverter-to-be then try to work it out on the `django-developers`_
+ mailing list. If an agreement can't be reached then it should
+ be put to a vote.
+
+ * If the commit introduced a confirmed, disclosed security
+ vulnerability then the commit may be reverted immediately without
+ permission from anyone.
+
+ * The release branch maintainer may back out commits to the release
+ branch without permission if the commit breaks the release branch.
+
+.. _unit-tests:
+
+Unit tests
+==========
+
+Django comes with a test suite of its own, in the ``tests`` directory of the
+Django tarball. It's our policy to make sure all tests pass at all times.
+
+The tests cover:
+
+ * Models and the database API (``tests/modeltests/``).
+ * Everything else in core Django code (``tests/regressiontests``)
+ * Contrib apps (``django/contrib/<contribapp>/tests``, see below)
+
+We appreciate any and all contributions to the test suite!
+
+The Django tests all use the testing infrastructure that ships with Django for
+testing applications. See :doc:`Testing Django applications </topics/testing>`
+for an explanation of how to write new tests.
+
+.. _running-unit-tests:
+
+Running the unit tests
+----------------------
+
+To run the tests, ``cd`` to the ``tests/`` directory and type:
+
+.. code-block:: bash
+
+ ./runtests.py --settings=path.to.django.settings
+
+Yes, the unit tests need a settings module, but only for database connection
+info. Your :setting:`DATABASES` setting needs to define two databases:
+
+ * A ``default`` database. This database should use the backend that
+ you want to use for primary testing
+
+ * A database with the alias ``other``. The ``other`` database is
+ used to establish that queries can be directed to different
+ databases. As a result, this database can use any backend you
+ want. It doesn't need to use the same backend as the ``default``
+ database (although it can use the same backend if you want to).
+
+If you're using the SQLite database backend, you need to define
+:setting:`ENGINE` for both databases, plus a
+:setting:`TEST_NAME` for the ``other`` database. The
+following is a minimal settings file that can be used to test SQLite::
+
+ DATABASES = {
+ 'default': {
+ 'ENGINE': 'django.db.backends.sqlite3'
+ },
+ 'other': {
+ 'ENGINE': 'django.db.backends.sqlite3',
+ 'TEST_NAME': 'other_db'
+ }
+ }
+
+As a convenience, this settings file is included in your Django
+distribution. It is called ``test_sqlite``, and is included in
+the ``tests`` directory. This allows you to get started running
+the tests against the sqlite database without doing anything on
+your filesystem. However it should be noted that running against
+other database backends is recommended for certain types of test
+cases.
+
+To run the tests with this included settings file, ``cd``
+to the ``tests/`` directory and type:
+
+.. code-block:: bash
+
+ ./runtests.py --settings=test_sqlite
+
+If you're using another backend, you will need to provide other details for
+each database:
+
+ * The :setting:`USER` option for each of your databases needs to
+ specify an existing user account for the database.
+
+ * The :setting:`PASSWORD` option needs to provide the password for
+ the :setting:`USER` that has been specified.
+
+ * The :setting:`NAME` option must be the name of an existing database to
+ which the given user has permission to connect. The unit tests will not
+ touch this database; the test runner creates a new database whose name is
+ :setting:`NAME` prefixed with ``test_``, and this test database is
+ deleted when the tests are finished. This means your user account needs
+ permission to execute ``CREATE DATABASE``.
+
+You will also need to ensure that your database uses UTF-8 as the default
+character set. If your database server doesn't use UTF-8 as a default charset,
+you will need to include a value for ``TEST_CHARSET`` in the settings
+dictionary for the applicable database.
+
+If you want to run the full suite of tests, you'll need to install a number of
+dependencies:
+
+ * PyYAML_
+ * Markdown_
+ * Textile_
+ * Docutils_
+ * setuptools_
+ * memcached_, plus the either the python-memcached_ or cmemcached_
+ Python binding
+ * gettext_ (:ref:`gettext_on_windows`)
+
+If you want to test the memcached cache backend, you will also need to define
+a :setting:`CACHE_BACKEND` setting that points at your memcached instance.
+
+Each of these dependencies is optional. If you're missing any of them, the
+associated tests will be skipped.
+
+.. _PyYAML: http://pyyaml.org/wiki/PyYAML
+.. _Markdown: http://pypi.python.org/pypi/Markdown/1.7
+.. _Textile: http://pypi.python.org/pypi/textile
+.. _docutils: http://pypi.python.org/pypi/docutils/0.4
+.. _setuptools: http://pypi.python.org/pypi/setuptools/
+.. _memcached: http://www.danga.com/memcached/
+.. _python-memcached: http://pypi.python.org/pypi/python-memcached/
+.. _cmemcached: http://gijsbert.org/cmemcache/index.html
+.. _gettext: http://www.gnu.org/software/gettext/manual/gettext.html
+
+To run a subset of the unit tests, append the names of the test modules to the
+``runtests.py`` command line. See the list of directories in
+``tests/modeltests`` and ``tests/regressiontests`` for module names.
+
+As an example, if Django is not in your ``PYTHONPATH``, you placed
+``settings.py`` in the ``tests/`` directory, and you'd like to only run tests
+for generic relations and internationalization, type:
+
+.. code-block:: bash
+
+ PYTHONPATH=`pwd`/..
+ ./runtests.py --settings=settings generic_relations i18n
+
+Contrib apps
+------------
+
+Tests for apps in ``django/contrib/`` go in their respective directories under
+``django/contrib/``, in a ``tests.py`` file. (You can split the tests over
+multiple modules by using a ``tests`` directory in the normal Python way.)
+
+For the tests to be found, a ``models.py`` file must exist (it doesn't
+have to have anything in it). If you have URLs that need to be
+mapped, put them in ``tests/urls.py``.
+
+To run tests for just one contrib app (e.g. ``markup``), use the same
+method as above::
+
+ ./runtests.py --settings=settings markup
+
+Requesting features
+===================
+
+We're always trying to make Django better, and your feature requests are a key
+part of that. Here are some tips on how to most effectively make a request:
+
+ * Request the feature on `django-developers`_, not in the ticket tracker;
+ it'll get read more closely if it's on the mailing list.
+
+ * Describe clearly and concisely what the missing feature is and how you'd
+ like to see it implemented. Include example code (non-functional is OK)
+ if possible.
+
+ * Explain *why* you'd like the feature. In some cases this is obvious, but
+ since Django is designed to help real developers get real work done,
+ you'll need to explain it, if it isn't obvious why the feature would be
+ useful.
+
+As with most open-source projects, code talks. If you are willing to write the
+code for the feature yourself or if (even better) you've already written it,
+it's much more likely to be accepted. If it's a large feature that might need
+multiple developers we're always happy to give you an experimental branch in
+our repository; see below.
+
+Branch policy
+=============
+
+In general, the trunk must be kept stable. People should be able to run
+production sites against the trunk at any time. Additionally, commits to trunk
+ought to be as atomic as possible -- smaller changes are better. Thus, large
+feature changes -- that is, changes too large to be encapsulated in a single
+patch, or changes that need multiple eyes on them -- must happen on dedicated
+branches.
+
+This means that if you want to work on a large feature -- anything that would
+take more than a single patch, or requires large-scale refactoring -- you need
+to do it on a feature branch. Our development process recognizes two options
+for feature branches:
+
+ 1. Feature branches using a distributed revision control system like
+ Git_, Mercurial_, Bazaar_, etc.
+
+ If you're familiar with one of these tools, this is probably your best
+ option since it doesn't require any support or buy-in from the Django
+ core developers.
+
+ However, do keep in mind that Django will continue to use Subversion for
+ the foreseeable future, and this will naturally limit the recognition of
+ your branch. Further, if your branch becomes eligible for merging to
+ trunk you'll need to find a core developer familiar with your DVCS of
+ choice who'll actually perform the merge.
+
+ If you do decided to start a distributed branch of Django and choose to make it
+ public, please add the branch to the `Django branches`_ wiki page.
+
+ 2. Feature branches using SVN have a higher bar. If you want a branch in SVN
+ itself, you'll need a "mentor" among the :doc:`core committers
+ </internals/committers>`. This person is responsible for actually creating
+ the branch, monitoring your process (see below), and ultimately merging
+ the branch into trunk.
+
+ If you want a feature branch in SVN, you'll need to ask in
+ `django-developers`_ for a mentor.
+
+.. _git: http://git-scm.com/
+.. _mercurial: http://mercurial.selenic.com/
+.. _bazaar: http://bazaar.canonical.com/
+.. _django branches: http://code.djangoproject.com/wiki/DjangoBranches
+
+Branch rules
+------------
+
+We've got a few rules for branches born out of experience with what makes a
+successful Django branch.
+
+DVCS branches are obviously not under central control, so we have no way of
+enforcing these rules. However, if you're using a DVCS, following these rules
+will give you the best chance of having a successful branch (read: merged back to
+trunk).
+
+Developers with branches in SVN, however, **must** follow these rules. The
+branch mentor will keep on eye on the branch and **will delete it** if these
+rules are broken.
+
+ * Only branch entire copies of the Django tree, even if work is only
+ happening on part of that tree. This makes it painless to switch to a
+ branch.
+
+ * Merge changes from trunk no less than once a week, and preferably every
+ couple-three days.
+
+ In our experience, doing regular trunk merges is often the difference
+ between a successful branch and one that fizzles and dies.
+
+ If you're working on an SVN branch, you should be using `svnmerge.py`_
+ to track merges from trunk.
+
+ * Keep tests passing and documentation up-to-date. As with patches,
+ we'll only merge a branch that comes with tests and documentation.
+
+.. _svnmerge.py: http://www.orcaware.com/svn/wiki/Svnmerge.py
+
+Once the branch is stable and ready to be merged into the trunk, alert
+`django-developers`_.
+
+After a branch has been merged, it should be considered "dead"; write access to
+it will be disabled, and old branches will be periodically "trimmed." To keep
+our SVN wrangling to a minimum, we won't be merging from a given branch into the
+trunk more than once.
+
+Using branches
+--------------
+
+To use a branch, you'll need to do two things:
+
+ * Get the branch's code through Subversion.
+
+ * Point your Python ``site-packages`` directory at the branch's version of
+ the ``django`` package rather than the version you already have
+ installed.
+
+Getting the code from Subversion
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To get the latest version of a branch's code, check it out using Subversion:
+
+.. code-block:: bash
+
+ svn co http://code.djangoproject.com/svn/django/branches/<branch>/
+
+...where ``<branch>`` is the branch's name. See the `list of branch names`_.
+
+Alternatively, you can automatically convert an existing directory of the
+Django source code as long as you've checked it out via Subversion. To do the
+conversion, execute this command from within your ``django`` directory:
+
+.. code-block:: bash
+
+ svn switch http://code.djangoproject.com/svn/django/branches/<branch>/
+
+The advantage of using ``svn switch`` instead of ``svn co`` is that the
+``switch`` command retains any changes you might have made to your local copy
+of the code. It attempts to merge those changes into the "switched" code. The
+disadvantage is that it may cause conflicts with your local changes if the
+"switched" code has altered the same lines of code.
+
+(Note that if you use ``svn switch``, you don't need to point Python at the new
+version, as explained in the next section.)
+
+.. _list of branch names: http://code.djangoproject.com/browser/django/branches
+
+Pointing Python at the new Django version
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Once you've retrieved the branch's code, you'll need to change your Python
+``site-packages`` directory so that it points to the branch version of the
+``django`` directory. (The ``site-packages`` directory is somewhere such as
+``/usr/lib/python2.4/site-packages`` or
+``/usr/local/lib/python2.4/site-packages`` or ``C:\Python\site-packages``.)
+
+The simplest way to do this is by renaming the old ``django`` directory to
+``django.OLD`` and moving the trunk version of the code into the directory
+and calling it ``django``.
+
+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
+``setuptools.pth`` and remove the line that references the Django ``.egg``
+file. Then copy the branch's version of the ``django`` directory into
+``site-packages``.
+
+.. _path file: http://docs.python.org/library/site.html
+
+How we make decisions
+=====================
+
+Whenever possible, we strive for a rough consensus. To that end, we'll often
+have informal votes on `django-developers`_ about a feature. In these votes we
+follow the voting style invented by Apache and used on Python itself, where
+votes are given as +1, +0, -0, or -1. Roughly translated, these votes mean:
+
+ * +1: "I love the idea and I'm strongly committed to it."
+
+ * +0: "Sounds OK to me."
+
+ * -0: "I'm not thrilled, but I won't stand in the way."
+
+ * -1: "I strongly disagree and would be very unhappy to see the idea turn
+ into reality."
+
+Although these votes on django-developers are informal, they'll be taken very
+seriously. After a suitable voting period, if an obvious consensus arises
+we'll follow the votes.
+
+However, consensus is not always possible. If consensus cannot be reached, or
+if the discussion towards a consensus fizzles out without a concrete decision,
+we use a more formal process.
+
+Any core committer (see below) may call for a formal vote using the same
+voting mechanism above. A proposition will be considered carried by the core team
+if:
+
+ * There are three "+1" votes from members of the core team.
+
+ * There is no "-1" vote from any member of the core team.
+
+ * The BDFLs haven't stepped in and executed their positive or negative
+ veto.
+
+When calling for a vote, the caller should specify a deadline by which
+votes must be received. One week is generally suggested as the minimum
+amount of time.
+
+Since this process allows any core committer to veto a proposal, any "-1"
+votes (or BDFL vetos) should be accompanied by an explanation that explains
+what it would take to convert that "-1" into at least a "+0".
+
+Whenever possible, these formal votes should be announced and held in
+public on the `django-developers`_ mailing list. However, overly sensitive
+or contentious issues -- including, most notably, votes on new core
+committers -- may be held in private.
+
+Commit access
+=============
+
+Django has two types of committers:
+
+Core committers
+ These are people who have a long history of contributions to Django's
+ codebase, a solid track record of being polite and helpful on the
+ mailing lists, and a proven desire to dedicate serious time to Django's
+ development. The bar is high for full commit access.
+
+Partial committers
+ These are people who are "domain experts." They have direct check-in access
+ to the subsystems that fall under their jurisdiction, and they're given a
+ formal vote in questions that involve their subsystems. This type of access
+ is likely to be given to someone who contributes a large subframework to
+ Django and wants to continue to maintain it.
+
+ Partial commit access is granted by the same process as full
+ committers. However, the bar is set lower; proven expertise in the area
+ in question is likely to be sufficient.
+
+Decisions on new committers will follow the process explained above in `how
+we make decisions`_.
+
+To request commit access, please contact an existing committer privately. Public
+requests for commit access are potential flame-war starters, and will be ignored.
+
+.. _community page: http://www.djangoproject.com/community/
+.. _ticket tracker: http://code.djangoproject.com/newticket
+.. _django-developers: http://groups.google.com/group/django-developers
+.. _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/query?status=new&status=assigned&status=reopened&has_patch=1&order=priority
+.. _pep8.py: http://pypi.python.org/pypi/pep8/
+.. _i18n branch: http://code.djangoproject.com/browser/django/branches/i18n
+.. _`tags/releases`: http://code.djangoproject.com/browser/django/tags/releases
+.. _`easy-pickings`: http://code.djangoproject.com/query?status=new&status=assigned&status=reopened&keywords=~easy-pickings&order=priority