1 ======================

     2 Contributing to Django

     3 ======================

     4 

     5 If you think working *with* Django is fun, wait until you start working *on* it.

     6 We're passionate about helping Django users make the jump to contributing members

     7 of the community, so there are many ways you can help Django's development:

     8 

     9     * Blog about Django.  We syndicate all the Django blogs we know about on

    10       the `community page`_; contact jacob@jacobian.org if you've got a blog

    11       you'd like to see on that page.

    12 

    13     * Report bugs and request features in our `ticket tracker`_.  Please read

    14       `Reporting bugs`_, below, for the details on how we like our bug reports

    15       served up.

    16 

    17     * Submit patches for new and/or fixed behavior.  Please read `Submitting

    18       patches`_, below, for details on how to submit a patch. If you're looking

    19       for an easy way to start contributing to Django have a look at the

    20       `easy-pickings`_ tickets.

    21 

    22     * Join the `django-developers`_ mailing list and share your ideas for how

    23       to improve Django.  We're always open to suggestions, although we're

    24       likely to be skeptical of large-scale suggestions without some code to

    25       back it up.

    26 

    27     * Triage patches that have been submitted by other users. Please read

    28       `Ticket triage`_ below, for details on the triage process.

    29 

    30 That's all you need to know if you'd like to join the Django development

    31 community. The rest of this document describes the details of how our community

    32 works and how it handles bugs, mailing lists, and all the other minutiae of

    33 Django development.

    34 

    35 .. _reporting-bugs:

    36 

    37 Reporting bugs

    38 ==============

    39 

    40 Well-written bug reports are *incredibly* helpful. However, there's a certain

    41 amount of overhead involved in working with any bug tracking system, so your

    42 help in keeping our ticket tracker as useful as possible is appreciated.  In

    43 particular:

    44 

    45     * **Do** read the :doc:`FAQ </faq/index>` to see if your issue might be a well-known question.

    46 

    47     * **Do** `search the tracker`_ to see if your issue has already been filed.

    48 

    49     * **Do** ask on `django-users`_ *first* if you're not sure if what you're

    50       seeing is a bug.

    51 

    52     * **Do** write complete, reproducible, specific bug reports. Include as

    53       much information as you possibly can, complete with code snippets, test

    54       cases, etc. This means including a clear, concise description of the

    55       problem, and a clear set of instructions for replicating the problem.

    56       A minimal example that illustrates the bug in a nice small test case

    57       is the best possible bug report.

    58 

    59     * **Don't** use the ticket system to ask support questions.  Use the

    60       `django-users`_ list, or the `#django`_ IRC channel for that.

    61 

    62     * **Don't** use the ticket system to make large-scale feature requests.

    63       We like to discuss any big changes to Django's core on the `django-developers`_

    64       list before actually working on them.

    65 

    66     * **Don't** reopen issues that have been marked "wontfix". This mark means

    67       that the decision has been made that we can't or won't fix this particular

    68       issue.  If you're not sure why, please ask on `django-developers`_.

    69 

    70     * **Don't** use the ticket tracker for lengthy discussions, because they're

    71       likely to get lost. If a particular ticket is controversial, please move

    72       discussion to `django-developers`_.

    73 

    74     * **Don't** post to django-developers just to announce that you have filed

    75       a bug report. All the tickets are mailed to another list

    76       (`django-updates`_), which is tracked by developers and triagers, so we

    77       see them as they are filed.

    78 

    79 .. _django-updates: http://groups.google.com/group/django-updates

    80 

    81 .. _reporting-security-issues:

    82 

    83 Reporting security issues

    84 =========================

    85 

    86 Report security issues to security@djangoproject.com. This is a private list

    87 only open to long-time, highly trusted Django developers, and its archives are

    88 not publicly readable.

    89 

    90 In the event of a confirmed vulnerability in Django itself, we will take the

    91 following actions:

    92 

    93     * Acknowledge to the reporter that we've received the report and that a fix

    94       is forthcoming. We'll give a rough timeline and ask the reporter to keep

    95       the issue confidential until we announce it.

    96 

    97     * Halt all other development as long as is needed to develop a fix, including

    98       patches against the current and two previous releases.

    99 

   100     * Determine a go-public date for announcing the vulnerability and the fix.

   101       To try to mitigate a possible "arms race" between those applying the patch

   102       and those trying to exploit the hole, we will not announce security

   103       problems immediately.

   104 

   105     * Pre-notify everyone we know to be running the affected version(s) of

   106       Django. We will send these notifications through private e-mail which will

   107       include documentation of the vulnerability, links to the relevant patch(es),

   108       and a request to keep the vulnerability confidential until the official

   109       go-public date.

   110 

   111     * Publicly announce the vulnerability and the fix on the pre-determined

   112       go-public date. This will probably mean a new release of Django, but

   113       in some cases it may simply be patches against current releases.

   114 

   115 Submitting patches

   116 ==================

   117 

   118 We're always grateful for patches to Django's code. Indeed, bug reports with

   119 associated patches will get fixed *far* more quickly than those without patches.

   120 

   121 "Claiming" tickets

   122 ------------------

   123 

   124 In an open-source project with hundreds of contributors around the world, it's

   125 important to manage communication efficiently so that work doesn't get

   126 duplicated and contributors can be as effective as possible. Hence, our policy

   127 is for contributors to "claim" tickets in order to let other developers know

   128 that a particular bug or feature is being worked on.

   129 

   130 If you have identified a contribution you want to make and you're capable of

   131 fixing it (as measured by your coding ability, knowledge of Django internals

   132 and time availability), claim it by following these steps:

   133 

   134     * `Create an account`_ to use in our ticket system.

   135     * If a ticket for this issue doesn't exist yet, create one in our

   136       `ticket tracker`_.

   137     * If a ticket for this issue already exists, make sure nobody else has

   138       claimed it. To do this, look at the "Assigned to" section of the ticket.

   139       If it's assigned to "nobody," then it's available to be claimed.

   140       Otherwise, somebody else is working on this ticket, and you either find

   141       another bug/feature to work on, or contact the developer working on the

   142       ticket to offer your help.

   143     * Log into your account, if you haven't already, by clicking "Login" in the

   144       upper right of the ticket page.

   145     * Claim the ticket by clicking the radio button next to "Accept ticket"

   146       near the bottom of the page, then clicking "Submit changes."

   147 

   148 If you have an account but have forgotten your password, you can reset it

   149 using the `password reset page`_.

   150 

   151 .. _Create an account: http://www.djangoproject.com/accounts/register/

   152 .. _password reset page: http://www.djangoproject.com/accounts/password/reset/

   153 

   154 Ticket claimers' responsibility

   155 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   156 

   157 Once you've claimed a ticket, you have a responsibility to work on that ticket

   158 in a reasonably timely fashion. If you don't have time to work on it, either

   159 unclaim it or don't claim it in the first place!

   160 

   161 Ticket triagers go through the list of claimed tickets from time to

   162 time, checking whether any progress has been made. If there's no sign of

   163 progress on a particular claimed ticket for a week or two, a triager may ask

   164 you to relinquish the ticket claim so that it's no longer monopolized and

   165 somebody else can claim it.

   166 

   167 If you've claimed a ticket and it's taking a long time (days or weeks) to code,

   168 keep everybody updated by posting comments on the ticket. If you don't provide

   169 regular updates, and you don't respond to a request for a progress report,

   170 your claim on the ticket may be revoked. As always, more communication is

   171 better than less communication!

   172 

   173 Which tickets should be claimed?

   174 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   175 

   176 Of course, going through the steps of claiming tickets is overkill in some

   177 cases. In the case of small changes, such as typos in the documentation or

   178 small bugs that will only take a few minutes to fix, you don't need to jump

   179 through the hoops of claiming tickets. Just submit your patch and be done with

   180 it.

   181 

   182 Patch style

   183 -----------

   184 

   185     * Make sure your code matches our `coding style`_.

   186 

   187     * Submit patches in the format returned by the ``svn diff`` command.

   188       An exception is for code changes that are described more clearly in plain

   189       English than in code. Indentation is the most common example; it's hard to

   190       read patches when the only difference in code is that it's indented.

   191 

   192       Patches in ``git diff`` format are also acceptable.

   193 

   194     * When creating patches, always run ``svn diff`` from the top-level

   195       ``trunk`` directory -- i.e., the one that contains ``django``, ``docs``,

   196       ``tests``, ``AUTHORS``, etc. This makes it easy for other people to apply

   197       your patches.

   198 

   199     * Attach patches to a ticket in the `ticket tracker`_, using the "attach file"

   200       button. Please *don't* put the patch in the ticket description or comment

   201       unless it's a single line patch.

   202 

   203     * Name the patch file with a ``.diff`` extension; this will let the ticket

   204       tracker apply correct syntax highlighting, which is quite helpful.

   205 

   206     * Check the "Has patch" box on the ticket details. This will make it

   207       obvious that the ticket includes a patch, and it will add the ticket to

   208       the `list of tickets with patches`_.

   209 

   210     * The code required to fix a problem or add a feature is an essential part

   211       of a patch, but it is not the only part. A good patch should also include

   212       a regression test to validate the behavior that has been fixed (and prevent

   213       the problem from arising again).

   214 

   215     * If the code associated with a patch adds a new feature, or modifies behavior

   216       of an existing feature, the patch should also contain documentation.

   217 

   218 Non-trivial patches

   219 -------------------

   220 

   221 A "non-trivial" patch is one that is more than a simple bug fix. It's a patch

   222 that introduces Django functionality and makes some sort of design decision.

   223 

   224 If you provide a non-trivial patch, include evidence that alternatives have

   225 been discussed on `django-developers`_. If you're not sure whether your patch

   226 should be considered non-trivial, just ask.

   227 

   228 Ticket triage

   229 =============

   230 

   231 Unfortunately, not all bug reports in the `ticket tracker`_ provide all

   232 the `required details`_. A number of tickets have patches, but those patches

   233 don't meet all the requirements of a `good patch`_.

   234 

   235 One way to help out is to *triage* bugs that have been reported by other

   236 users. A couple of dedicated volunteers work on this regularly, but more help

   237 is always appreciated.

   238 

   239 Most of the workflow is based around the concept of a ticket's "triage stage".

   240 This stage describes where in its lifetime a given ticket is at any time.

   241 Along with a handful of flags, this field easily tells us what and who each

   242 ticket is waiting on.

   243 

   244 Since a picture is worth a thousand words, let's start there:

   245 

   246 .. image:: _images/djangotickets.png

   247    :height: 451

   248    :width: 590

   249    :alt: Django's ticket workflow

   250 

   251 We've got two official roles here:

   252 

   253     * Core developers: people with commit access who make the big decisions

   254       and write the bulk of the code.

   255 

   256     * Ticket triagers: trusted community members with a proven history of

   257       working with the Django community. As a result of this history, they

   258       have been entrusted by the core developers to make some of the smaller

   259       decisions about tickets.

   260 

   261 Second, note the five triage stages:

   262 

   263     1. A ticket starts as "Unreviewed", meaning that nobody has examined

   264        the ticket.

   265 

   266     2. "Design decision needed" means "this concept requires a design

   267        decision," which should be discussed either in the ticket comments or on

   268        `django-developers`_. The "Design decision needed" step will generally

   269        only be used for feature requests. It can also be used for issues

   270        that *might* be bugs, depending on opinion or interpretation. Obvious

   271        bugs (such as crashes, incorrect query results, or non-compliance with a

   272        standard) skip this step and move straight to "Accepted".

   273 

   274     3. Once a ticket is ruled to be approved for fixing, it's moved into the

   275        "Accepted" stage. This stage is where all the real work gets done.

   276 

   277     4. In some cases, a ticket might get moved to the "Someday/Maybe" state.

   278        This means the ticket is an enhancement request that we might consider

   279        adding to the framework if an excellent patch is submitted. These

   280        tickets are not a high priority.

   281 

   282     5. If a ticket has an associated patch (see below), a triager will review

   283        the patch. If the patch is complete, it'll be marked as "ready for

   284        checkin" so that a core developer knows to review and check in the

   285        patches.

   286 

   287 The second part of this workflow involves a set of flags the describe what the

   288 ticket has or needs in order to be "ready for checkin":

   289 

   290     "Has patch"

   291         This means the ticket has an associated patch_. These will be

   292         reviewed by the triage team to see if the patch is "good".

   293 

   294     "Needs documentation"

   295         This flag is used for tickets with patches that need associated

   296         documentation. Complete documentation of features is a prerequisite

   297         before we can check a fix into the codebase.

   298 

   299     "Needs tests"

   300         This flags the patch as needing associated unit tests. Again, this is a

   301         required part of a valid patch.

   302 

   303     "Patch needs improvement"

   304         This flag means that although the ticket *has* a patch, it's not quite

   305         ready for checkin. This could mean the patch no longer applies

   306         cleanly, or that the code doesn't live up to our standards.

   307 

   308 A ticket can be resolved in a number of ways:

   309 

   310     "fixed"

   311         Used by one of the core developers once a patch has been rolled into

   312         Django and the issue is fixed.

   313 

   314     "invalid"

   315         Used if the ticket is found to be incorrect. This means that the

   316         issue in the ticket is actually the result of a user error, or

   317         describes a problem with something other than Django, or isn't

   318         a bug report or feature request at all (for example, some new users

   319         submit support queries as tickets).

   320 

   321     "wontfix"

   322         Used when a core developer decides that this request is not

   323         appropriate for consideration in Django. This is usually chosen after

   324         discussion in the ``django-developers`` mailing list, and you should

   325         feel free to join in when it's something you care about.

   326 

   327     "duplicate"

   328         Used when another ticket covers the same issue. By closing duplicate

   329         tickets, we keep all the discussion in one place, which helps everyone.

   330 

   331     "worksforme"

   332         Used when the ticket doesn't contain enough detail to replicate

   333         the original bug.

   334 

   335 If you believe that the ticket was closed in error -- because you're

   336 still having the issue, or it's popped up somewhere else, or the triagers have

   337 -- made a mistake, please reopen the ticket and tell us why. Please do not

   338 reopen tickets that have been marked as "wontfix" by core developers.

   339 

   340 .. _required details: `Reporting bugs`_

   341 .. _good patch: `Patch style`_

   342 .. _patch: `Submitting patches`_

   343 

   344 Triage by the general community

   345 -------------------------------

   346 

   347 Although the core developers and ticket triagers make the big decisions in

   348 the ticket triage process, there's also a lot that general community

   349 members can do to help the triage process. In particular, you can help out by:

   350 

   351     * Closing "Unreviewed" tickets as "invalid", "worksforme" or "duplicate."

   352 

   353     * Promoting "Unreviewed" tickets to "Design decision needed" if a design

   354       decision needs to be made, or "Accepted" in case of obvious bugs.

   355 

   356     * Correcting the "Needs tests", "Needs documentation", or "Has patch" flags

   357       for tickets where they are incorrectly set.

   358 

   359     * Adding the `easy-pickings`_ keyword to tickets that are small and

   360       relatively straightforward.

   361 

   362     * Checking that old tickets are still valid. If a ticket hasn't seen

   363       any activity in a long time, it's possible that the problem has been

   364       fixed but the ticket hasn't yet been closed.

   365 

   366     * Contacting the owners of tickets that have been claimed but have not seen

   367       any recent activity. If the owner doesn't respond after a week or so,

   368       remove the owner's claim on the ticket.

   369 

   370     * Identifying trends and themes in the tickets. If there a lot of bug reports

   371       about a particular part of Django, it may indicate we should consider

   372       refactoring that part of the code. If a trend is emerging, you should

   373       raise it for discussion (referencing the relevant tickets) on

   374       `django-developers`_.

   375 

   376 However, we do ask the following of all general community members working in

   377 the ticket database:

   378 

   379     * Please **don't** close tickets as "wontfix." The core developers will

   380       make the final determination of the fate of a ticket, usually after

   381       consultation with the community.

   382 

   383     * Please **don't** promote tickets to "Ready for checkin" unless they are

   384       *trivial* changes -- for example, spelling mistakes or broken links in

   385       documentation.

   386 

   387     * Please **don't** reverse a decision that has been made by a core

   388       developer. If you disagree with a discussion that has been made,

   389       please post a message to `django-developers`_.

   390 

   391     * Please be conservative in your actions. If you're unsure if you should

   392       be making a change, don't make the change -- leave a comment with your

   393       concerns on the ticket, or post a message to `django-developers`_.

   394 

   395 .. _contributing-translations:

   396 

   397 Submitting and maintaining translations

   398 =======================================

   399 

   400 Various parts of Django, such as the admin site and validation error messages,

   401 are internationalized. This means they display different text depending on a

   402 user's language setting. For this, Django uses the same internationalization

   403 infrastructure available to Django applications described in the

   404 :doc:`i18n documentation</topics/i18n/index>`.

   405 

   406 These translations are contributed by Django users worldwide. If you find an

   407 incorrect translation, or if you'd like to add a language that isn't yet

   408 translated, here's what to do:

   409 

   410     * Join the `Django i18n mailing list`_ and introduce yourself.

   411 

   412     * Make sure you read the notes about :ref:`specialties-of-django-i18n`.

   413 

   414     * Create translations using the methods described in the

   415       :doc:`localization documentation </topics/i18n/localization>`. For this

   416       you will use the ``django-admin.py makemessages`` tool. In this

   417       particular case it should be run from the top-level ``django`` directory

   418       of the Django source tree.

   419 

   420       The script runs over the entire Django source tree and pulls out all

   421       strings marked for translation. It creates (or updates) a message file in

   422       the directory ``conf/locale`` (for example for ``pt_BR``, the file will be

   423       ``conf/locale/pt_BR/LC_MESSAGES/django.po``).

   424 

   425     * Make sure that ``django-admin.py compilemessages -l <lang>`` runs without

   426       producing any warnings.

   427 

   428     * Repeat the last two steps for the ``djangojs`` domain (by appending the

   429       ``-d djangojs`` command line option to the ``django-admin.py``

   430       invocations).

   431 

   432     * Optionally, review and update the ``conf/locale/<locale>/formats.py``

   433       file to describe the date, time and numbers formatting particularities of

   434       your locale. See :ref:`format-localization` for details.

   435 

   436     * Create a diff against the current Subversion trunk.

   437 

   438     * Open a ticket in Django's ticket system, set its ``Component`` field to

   439       ``Translations``, and attach the patch to it.

   440 

   441 .. _Django i18n mailing list: http://groups.google.com/group/django-i18n/

   442 

   443 Submitting javascript patches

   444 =============================

   445 

   446 .. versionadded:: 1.2

   447 

   448 Django's admin system leverages the jQuery framework to increase the

   449 capabilities of the admin interface. In conjunction, there is an emphasis on

   450 admin javascript performance and minimizing overall admin media file size.

   451 Serving compressed or "minified" versions of javascript files is considered

   452 best practice in this regard.

   453 

   454 To that end, patches for javascript files should include both the original

   455 code for future development (e.g. "foo.js"), and a compressed version for

   456 production use (e.g. "foo.min.js"). Any links to the file in the codebase

   457 should point to the compressed version.

   458 

   459 To simplify the process of providing optimized javascript code, Django

   460 includes a handy script which should be used to create a "minified" version.

   461 This script is located at ``/contrib/admin/media/js/compress.py``.

   462 

   463 Behind the scenes, ``compress.py`` is a front-end for Google's

   464 `Closure Compiler`_ which is written in Java. However, the Closure Compiler

   465 library is not bundled with Django directly, so those wishing to contribute

   466 complete javascript patches will need to download and install the library

   467 independently.

   468 

   469 The Closure Compiler library requires Java version 6 or higher (Java 1.6 or

   470 higher on Mac OS X). Note that Mac OS X 10.5 and earlier did not ship with Java

   471 1.6 by default, so it may be necessary to upgrade your Java installation before

   472 the tool will be functional. Also note that even after upgrading Java, the

   473 default `/usr/bin/java` command may remain linked to the previous Java

   474 binary, so relinking that command may be necessary as well.

   475 

   476 Please don't forget to run ``compress.py`` and include the ``diff`` of the

   477 minified scripts when submitting patches for Django's javascript.

   478 

   479 .. _Closure Compiler: http://code.google.com/closure/compiler/

   480 

   481 Django conventions

   482 ==================

   483 

   484 Various Django-specific code issues are detailed in this section.

   485 

   486 Use of ``django.conf.settings``

   487 -------------------------------

   488 

   489 Modules should not in general use settings stored in ``django.conf.settings`` at

   490 the top level (i.e. evaluated when the module is imported). The explanation for

   491 this is as follows:

   492 

   493 Manual configuration of settings (i.e. not relying on the

   494 ``DJANGO_SETTINGS_MODULE`` environment variable) is allowed and possible as

   495 follows::

   496 

   497     from django.conf import settings

   498 

   499     settings.configure({}, SOME_SETTING='foo')

   500 

   501 However, if any setting is accessed before the ``settings.configure`` line, this

   502 will not work. (Internally, ``settings`` is a ``LazyObject`` which configures

   503 itself automatically when the settings are accessed if it has not already been

   504 configured).

   505 

   506 So, if there is a module containing some code as follows::

   507 

   508     from django.conf import settings

   509     from django.core.urlresolvers import get_callable

   510 

   511     default_foo_view = get_callable(settings.FOO_VIEW)

   512 

   513 ...then importing this module will cause the settings object to be configured.

   514 That means that the ability for third parties to import the module at the top

   515 level is incompatible with the ability to configure the settings object

   516 manually, or makes it very difficult in some circumstances.

   517 

   518 Instead of the above code, a level of laziness or indirection must be used, such

   519 as :class:`django.utils.functional.LazyObject`, :func:`django.utils.functional.lazy` or

   520 ``lambda``.

   521 

   522 Coding style

   523 ============

   524 

   525 Please follow these coding standards when writing code for inclusion in Django:

   526 

   527     * Unless otherwise specified, follow :pep:`8`.

   528 

   529       You could use a tool like `pep8.py`_ to check for some problems in this

   530       area, but remember that PEP 8 is only a guide, so respect the style of

   531       the surrounding code as a primary goal.

   532 

   533     * Use four spaces for indentation.

   534 

   535     * Use underscores, not camelCase, for variable, function and method names

   536       (i.e. ``poll.get_unique_voters()``, not ``poll.getUniqueVoters``).

   537 

   538     * Use ``InitialCaps`` for class names (or for factory functions that

   539       return classes).

   540 

   541     * Mark all strings for internationalization; see the :doc:`i18n

   542       documentation </topics/i18n/index>` for details.

   543 

   544     * In docstrings, use "action words" such as::

   545 

   546           def foo():

   547               """

   548               Calculates something and returns the result.

   549               """

   550               pass

   551 

   552       Here's an example of what not to do::

   553 

   554           def foo():

   555               """

   556               Calculate something and return the result.

   557               """

   558               pass

   559 

   560     * Please don't put your name in the code you contribute. Our policy is to

   561       keep contributors' names in the ``AUTHORS`` file distributed with Django

   562       -- not scattered throughout the codebase itself. Feel free to include a

   563       change to the ``AUTHORS`` file in your patch if you make more than a

   564       single trivial change.

   565 

   566 Template style

   567 --------------

   568 

   569     * In Django template code, put one (and only one) space between the curly

   570       brackets and the tag contents.

   571 

   572       Do this:

   573 

   574       .. code-block:: html+django

   575 

   576           {{ foo }}

   577 

   578       Don't do this:

   579 

   580       .. code-block:: html+django

   581 

   582           {{foo}}

   583 

   584 View style

   585 ----------

   586 

   587     * In Django views, the first parameter in a view function should be called

   588       ``request``.

   589 

   590       Do this::

   591 

   592           def my_view(request, foo):

   593               # ...

   594 

   595       Don't do this::

   596 

   597           def my_view(req, foo):

   598               # ...

   599 

   600 Model style

   601 -----------

   602 

   603     * Field names should be all lowercase, using underscores instead of

   604       camelCase.

   605 

   606       Do this::

   607 

   608           class Person(models.Model):

   609               first_name = models.CharField(max_length=20)

   610               last_name = models.CharField(max_length=40)

   611 

   612       Don't do this::

   613 

   614           class Person(models.Model):

   615               FirstName = models.CharField(max_length=20)

   616               Last_Name = models.CharField(max_length=40)

   617 

   618     * The ``class Meta`` should appear *after* the fields are defined, with

   619       a single blank line separating the fields and the class definition.

   620 

   621       Do this::

   622 

   623           class Person(models.Model):

   624               first_name = models.CharField(max_length=20)

   625               last_name = models.CharField(max_length=40)

   626 

   627               class Meta:

   628                   verbose_name_plural = 'people'

   629 

   630       Don't do this::

   631 

   632           class Person(models.Model):

   633               first_name = models.CharField(max_length=20)

   634               last_name = models.CharField(max_length=40)

   635               class Meta:

   636                   verbose_name_plural = 'people'

   637 

   638       Don't do this, either::

   639 

   640           class Person(models.Model):

   641               class Meta:

   642                   verbose_name_plural = 'people'

   643 

   644               first_name = models.CharField(max_length=20)

   645               last_name = models.CharField(max_length=40)

   646 

   647     * The order of model inner classes and standard methods should be as

   648       follows (noting that these are not all required):

   649 

   650         * All database fields

   651         * Custom manager attributes

   652         * ``class Meta``

   653         * ``def __unicode__()``

   654         * ``def __str__()``

   655         * ``def save()``

   656         * ``def get_absolute_url()``

   657         * Any custom methods

   658 

   659     * If ``choices`` is defined for a given model field, define the choices as

   660       a tuple of tuples, with an all-uppercase name, either near the top of the

   661       model module or just above the model class. Example::

   662 

   663           GENDER_CHOICES = (

   664               ('M', 'Male'),

   665               ('F', 'Female'),

   666           )

   667 

   668 Documentation style

   669 ===================

   670 

   671 We place a high importance on consistency and readability of documentation.

   672 (After all, Django was created in a journalism environment!)

   673 

   674 How to document new features

   675 ----------------------------

   676 

   677 We treat our documentation like we treat our code: we aim to improve it as

   678 often as possible. This section explains how writers can craft their

   679 documentation changes in the most useful and least error-prone ways.

   680 

   681 Documentation changes come in two forms:

   682 

   683     * General improvements -- Typo corrections, error fixes and better

   684       explanations through clearer writing and more examples.

   685 

   686     * New features -- Documentation of features that have been added to the

   687       framework since the last release.

   688 

   689 Our policy is:

   690 

   691     **All documentation of new features should be written in a way that clearly

   692     designates the features are only available in the Django development

   693     version. Assume documentation readers are using the latest release, not the

   694     development version.**

   695 

   696 Our preferred way for marking new features is by prefacing the features'

   697 documentation with: ".. versionadded:: X.Y", followed by an optional one line

   698 comment and a mandatory blank line.

   699 

   700 General improvements, or other changes to the APIs that should be emphasized

   701 should use the ".. versionchanged:: X.Y" directive (with the same format as the

   702 ``versionadded`` mentioned above.

   703 

   704 There's a full page of information about the :doc:`Django documentation

   705 system </internals/documentation>` that you should read prior to working on the

   706 documentation.

   707 

   708 Guidelines for reST files

   709 -------------------------

   710 

   711 These guidelines regulate the format of our reST documentation:

   712 

   713     * In section titles, capitalize only initial words and proper nouns.

   714 

   715     * Wrap the documentation at 80 characters wide, unless a code example

   716       is significantly less readable when split over two lines, or for another

   717       good reason.

   718 

   719 Commonly used terms

   720 -------------------

   721 

   722 Here are some style guidelines on commonly used terms throughout the

   723 documentation:

   724 

   725     * **Django** -- when referring to the framework, capitalize Django. It is

   726       lowercase only in Python code and in the djangoproject.com logo.

   727 

   728     * **e-mail** -- it has a hyphen.

   729 

   730     * **MySQL**

   731 

   732     * **PostgreSQL**

   733 

   734     * **Python** -- when referring to the language, capitalize Python.

   735 

   736     * **realize**, **customize**, **initialize**, etc. -- use the American

   737       "ize" suffix, not "ise."

   738 

   739     * **SQLite**

   740 

   741     * **subclass** -- it's a single word without a hyphen, both as a verb

   742       ("subclass that model") and as a noun ("create a subclass").

   743 

   744     * **Web**, **World Wide Web**, **the Web** -- note Web is always

   745       capitalized when referring to the World Wide Web.

   746 

   747     * **Web site** -- use two words, with Web capitalized.

   748 

   749 Django-specific terminology

   750 ---------------------------

   751 

   752     * **model** -- it's not capitalized.

   753 

   754     * **template** -- it's not capitalized.

   755 

   756     * **URLconf** -- use three capitalized letters, with no space before

   757       "conf."

   758 

   759     * **view** -- it's not capitalized.

   760 

   761 Committing code

   762 ===============

   763 

   764 Please follow these guidelines when committing code to Django's Subversion

   765 repository:

   766 

   767     * For any medium-to-big changes, where "medium-to-big" is according to your

   768       judgment, please bring things up on the `django-developers`_ mailing list

   769       before making the change.

   770 

   771       If you bring something up on `django-developers`_ and nobody responds,

   772       please don't take that to mean your idea is great and should be

   773       implemented immediately because nobody contested it. Django's lead

   774       developers don't have a lot of time to read mailing-list discussions

   775       immediately, so you may have to wait a couple of days before getting a

   776       response.

   777 

   778     * Write detailed commit messages in the past tense, not present tense.

   779 

   780           * Good: "Fixed Unicode bug in RSS API."

   781           * Bad: "Fixes Unicode bug in RSS API."

   782           * Bad: "Fixing Unicode bug in RSS API."

   783 

   784     * For commits to a branch, prefix the commit message with the branch name.

   785       For example: "magic-removal: Added support for mind reading."

   786 

   787     * Limit commits to the most granular change that makes sense. This means,

   788       use frequent small commits rather than infrequent large commits. For

   789       example, if implementing feature X requires a small change to library Y,

   790       first commit the change to library Y, then commit feature X in a separate

   791       commit. This goes a *long way* in helping all core Django developers

   792       follow your changes.

   793 

   794     * Separate bug fixes from feature changes.

   795 

   796       Bug fixes need to be added to the current bugfix branch (e.g. the

   797       ``1.0.X`` branch) as well as the current trunk.

   798 

   799     * If your commit closes a ticket in the Django `ticket tracker`_, begin

   800       your commit message with the text "Fixed #abc", where "abc" is the number

   801       of the ticket your commit fixes. Example: "Fixed #123 -- Added support

   802       for foo". We've rigged Subversion and Trac so that any commit message

   803       in that format will automatically close the referenced ticket and post a

   804       comment to it with the full commit message.

   805 

   806       If your commit closes a ticket and is in a branch, use the branch name

   807       first, then the "Fixed #abc." For example:

   808       "magic-removal: Fixed #123 -- Added whizbang feature."

   809 

   810       For the curious: We're using a `Trac post-commit hook`_ for this.

   811 

   812       .. _Trac post-commit hook: http://trac.edgewall.org/browser/trunk/contrib/trac-post-commit-hook

   813 

   814     * If your commit references a ticket in the Django `ticket tracker`_ but

   815       does *not* close the ticket, include the phrase "Refs #abc", where "abc"

   816       is the number of the ticket your commit references. We've rigged

   817       Subversion and Trac so that any commit message in that format will

   818       automatically post a comment to the appropriate ticket.

   819 

   820 Reverting commits

   821 -----------------

   822 

   823 Nobody's perfect; mistakes will be committed. When a mistaken commit is

   824 discovered, please follow these guidelines:

   825 

   826     * Try very hard to ensure that mistakes don't happen. Just because we

   827       have a reversion policy doesn't relax your responsibility to aim for

   828       the highest quality possible. Really: double-check your work before

   829       you commit it in the first place!

   830       

   831     * If possible, have the original author revert his/her own commit.

   832       

   833     * Don't revert another author's changes without permission from the

   834       original author.

   835       

   836     * If the original author can't be reached (within a reasonable amount

   837       of time -- a day or so) and the problem is severe -- crashing bug,

   838       major test failures, etc -- then ask for objections on django-dev

   839       then revert if there are none.

   840       

   841     * If the problem is small (a feature commit after feature freeze,

   842       say), wait it out.

   843       

   844     * If there's a disagreement between the committer and the

   845       reverter-to-be then try to work it out on the `django-developers`_

   846       mailing list. If an agreement can't be reached then it should

   847       be put to a vote.

   848       

   849     * If the commit introduced a confirmed, disclosed security

   850       vulnerability then the commit may be reverted immediately without

   851       permission from anyone.

   852     

   853     * The release branch maintainer may back out commits to the release

   854       branch without permission if the commit breaks the release branch.

   855 

   856 .. _unit-tests:

   857 

   858 Unit tests

   859 ==========

   860 

   861 Django comes with a test suite of its own, in the ``tests`` directory of the

   862 Django tarball. It's our policy to make sure all tests pass at all times.

   863 

   864 The tests cover:

   865 

   866     * Models and the database API (``tests/modeltests/``).

   867     * Everything else in core Django code (``tests/regressiontests``)

   868     * Contrib apps (``django/contrib/<contribapp>/tests``, see below)

   869 

   870 We appreciate any and all contributions to the test suite!

   871 

   872 The Django tests all use the testing infrastructure that ships with Django for

   873 testing applications. See :doc:`Testing Django applications </topics/testing>`

   874 for an explanation of how to write new tests.

   875 

   876 .. _running-unit-tests:

   877 

   878 Running the unit tests

   879 ----------------------

   880 

   881 To run the tests, ``cd`` to the ``tests/`` directory and type:

   882 

   883 .. code-block:: bash

   884 

   885     ./runtests.py --settings=path.to.django.settings

   886 

   887 Yes, the unit tests need a settings module, but only for database connection

   888 info. Your :setting:`DATABASES` setting needs to define two databases:

   889 

   890     * A ``default`` database. This database should use the backend that

   891       you want to use for primary testing

   892 

   893     * A database with the alias ``other``. The ``other`` database is

   894       used to establish that queries can be directed to different

   895       databases. As a result, this database can use any backend you

   896       want. It doesn't need to use the same backend as the ``default``

   897       database (although it can use the same backend if you want to).

   898 

   899 If you're using the SQLite database backend, you need to define

   900 :setting:`ENGINE` for both databases, plus a

   901 :setting:`TEST_NAME` for the ``other`` database. The

   902 following is a minimal settings file that can be used to test SQLite::

   903 

   904     DATABASES = {

   905         'default': {

   906             'ENGINE': 'django.db.backends.sqlite3'

   907         },

   908         'other': {

   909             'ENGINE': 'django.db.backends.sqlite3',

   910             'TEST_NAME': 'other_db'

   911         }

   912     }

   913 

   914 As a convenience, this settings file is included in your Django

   915 distribution. It is called ``test_sqlite``, and is included in

   916 the ``tests`` directory. This allows you to get started running

   917 the tests against the sqlite database without doing anything on

   918 your filesystem. However it should be noted that running against

   919 other database backends is recommended for certain types of test

   920 cases.

   921 

   922 To run the tests with this included settings file, ``cd``

   923 to the ``tests/`` directory and type:

   924 

   925 .. code-block:: bash

   926 

   927     ./runtests.py --settings=test_sqlite

   928 

   929 If you're using another backend, you will need to provide other details for

   930 each database:

   931 

   932     * The :setting:`USER` option for each of your databases needs to

   933       specify an existing user account for the database.

   934 

   935     * The :setting:`PASSWORD` option needs to provide the password for

   936       the :setting:`USER` that has been specified.

   937 

   938     * The :setting:`NAME` option must be the name of an existing database to

   939       which the given user has permission to connect. The unit tests will not

   940       touch this database; the test runner creates a new database whose name is

   941       :setting:`NAME` prefixed with ``test_``, and this test database is

   942       deleted when the tests are finished. This means your user account needs

   943       permission to execute ``CREATE DATABASE``.

   944 

   945 You will also need to ensure that your database uses UTF-8 as the default

   946 character set. If your database server doesn't use UTF-8 as a default charset,

   947 you will need to include a value for ``TEST_CHARSET`` in the settings

   948 dictionary for the applicable database.

   949 

   950 If you want to run the full suite of tests, you'll need to install a number of

   951 dependencies:

   952 

   953     *  PyYAML_

   954     *  Markdown_

   955     *  Textile_

   956     *  Docutils_

   957     *  setuptools_

   958     *  memcached_, plus the either the python-memcached_ or cmemcached_

   959        Python binding

   960     *  gettext_ (:ref:`gettext_on_windows`)

   961 

   962 If you want to test the memcached cache backend, you will also need to define

   963 a :setting:`CACHE_BACKEND` setting that points at your memcached instance.

   964 

   965 Each of these dependencies is optional. If you're missing any of them, the

   966 associated tests will be skipped.

   967 

   968 .. _PyYAML: http://pyyaml.org/wiki/PyYAML

   969 .. _Markdown: http://pypi.python.org/pypi/Markdown/1.7

   970 .. _Textile: http://pypi.python.org/pypi/textile

   971 .. _docutils: http://pypi.python.org/pypi/docutils/0.4

   972 .. _setuptools: http://pypi.python.org/pypi/setuptools/

   973 .. _memcached: http://www.danga.com/memcached/

   974 .. _python-memcached: http://pypi.python.org/pypi/python-memcached/

   975 .. _cmemcached: http://gijsbert.org/cmemcache/index.html

   976 .. _gettext: http://www.gnu.org/software/gettext/manual/gettext.html

   977 

   978 To run a subset of the unit tests, append the names of the test modules to the

   979 ``runtests.py`` command line. See the list of directories in

   980 ``tests/modeltests`` and ``tests/regressiontests`` for module names.

   981 

   982 As an example, if Django is not in your ``PYTHONPATH``, you placed

   983 ``settings.py`` in the ``tests/`` directory, and you'd like to only run tests

   984 for generic relations and internationalization, type:

   985 

   986 .. code-block:: bash

   987 

   988     PYTHONPATH=`pwd`/..

   989     ./runtests.py --settings=settings generic_relations i18n

   990 

   991 Contrib apps

   992 ------------

   993 

   994 Tests for apps in ``django/contrib/`` go in their respective directories under

   995 ``django/contrib/``, in a ``tests.py`` file. (You can split the tests over

   996 multiple modules by using a ``tests`` directory in the normal Python way.)

   997 

   998 For the tests to be found, a ``models.py`` file must exist (it doesn't

   999 have to have anything in it). If you have URLs that need to be

  1000 mapped, put them in ``tests/urls.py``.

  1001 

  1002 To run tests for just one contrib app (e.g. ``markup``), use the same

  1003 method as above::

  1004 

  1005     ./runtests.py --settings=settings markup

  1006 

  1007 Requesting features

  1008 ===================

  1009 

  1010 We're always trying to make Django better, and your feature requests are a key

  1011 part of that. Here are some tips on how to most effectively make a request:

  1012 

  1013     * Request the feature on `django-developers`_, not in the ticket tracker;

  1014       it'll get read more closely if it's on the mailing list.

  1015 

  1016     * Describe clearly and concisely what the missing feature is and how you'd

  1017       like to see it implemented. Include example code (non-functional is OK)

  1018       if possible.

  1019 

  1020     * Explain *why* you'd like the feature. In some cases this is obvious, but

  1021       since Django is designed to help real developers get real work done,

  1022       you'll need to explain it, if it isn't obvious why the feature would be

  1023       useful.

  1024 

  1025 As with most open-source projects, code talks. If you are willing to write the

  1026 code for the feature yourself or if (even better) you've already written it,

  1027 it's much more likely to be accepted.  If it's a large feature that might need

  1028 multiple developers we're always happy to give you an experimental branch in

  1029 our repository; see below.

  1030 

  1031 Branch policy

  1032 =============

  1033 

  1034 In general, the trunk must be kept stable. People should be able to run

  1035 production sites against the trunk at any time. Additionally, commits to trunk

  1036 ought to be as atomic as possible -- smaller changes are better. Thus, large

  1037 feature changes -- that is, changes too large to be encapsulated in a single

  1038 patch, or changes that need multiple eyes on them -- must happen on dedicated

  1039 branches.

  1040 

  1041 This means that if you want to work on a large feature -- anything that would

  1042 take more than a single patch, or requires large-scale refactoring -- you need

  1043 to do it on a feature branch. Our development process recognizes two options

  1044 for feature branches:

  1045 

  1046     1. Feature branches using a distributed revision control system like

  1047        Git_, Mercurial_, Bazaar_, etc.

  1048 

  1049        If you're familiar with one of these tools, this is probably your best

  1050        option since it doesn't require any support or buy-in from the Django

  1051        core developers.

  1052 

  1053        However, do keep in mind that Django will continue to use Subversion for

  1054        the foreseeable future, and this will naturally limit the recognition of

  1055        your branch. Further, if your branch becomes eligible for merging to

  1056        trunk you'll need to find a core developer familiar with your DVCS of

  1057        choice who'll actually perform the merge.

  1058 

  1059        If you do decided to start a distributed branch of Django and choose to make it

  1060        public, please add the branch to the `Django branches`_ wiki page.

  1061 

  1062     2. Feature branches using SVN have a higher bar. If you want a branch in SVN

  1063        itself, you'll need a "mentor" among the :doc:`core committers

  1064        </internals/committers>`. This person is responsible for actually creating

  1065        the branch, monitoring your process (see below), and ultimately merging

  1066        the branch into trunk.

  1067 

  1068        If you want a feature branch in SVN, you'll need to ask in

  1069        `django-developers`_ for a mentor.

  1070 

  1071 .. _git: http://git-scm.com/

  1072 .. _mercurial: http://mercurial.selenic.com/

  1073 .. _bazaar: http://bazaar.canonical.com/

  1074 .. _django branches: http://code.djangoproject.com/wiki/DjangoBranches

  1075 

  1076 Branch rules

  1077 ------------

  1078 

  1079 We've got a few rules for branches born out of experience with what makes a

  1080 successful Django branch.

  1081 

  1082 DVCS branches are obviously not under central control, so we have no way of

  1083 enforcing these rules. However, if you're using a DVCS, following these rules

  1084 will give you the best chance of having a successful branch (read: merged back to

  1085 trunk).

  1086 

  1087 Developers with branches in SVN, however, **must** follow these rules. The

  1088 branch mentor will keep on eye on the branch and **will delete it** if these

  1089 rules are broken.

  1090 

  1091     * Only branch entire copies of the Django tree, even if work is only

  1092       happening on part of that tree. This makes it painless to switch to a

  1093       branch.

  1094 

  1095     * Merge changes from trunk no less than once a week, and preferably every

  1096       couple-three days.

  1097 

  1098       In our experience, doing regular trunk merges is often the difference

  1099       between a successful branch and one that fizzles and dies.

  1100 

  1101       If you're working on an SVN branch, you should be using `svnmerge.py`_

  1102       to track merges from trunk.

  1103 

  1104     * Keep tests passing and documentation up-to-date. As with patches,

  1105       we'll only merge a branch that comes with tests and documentation.

  1106 

  1107 .. _svnmerge.py: http://www.orcaware.com/svn/wiki/Svnmerge.py

  1108 

  1109 Once the branch is stable and ready to be merged into the trunk, alert

  1110 `django-developers`_.

  1111 

  1112 After a branch has been merged, it should be considered "dead"; write access to

  1113 it will be disabled, and old branches will be periodically "trimmed." To keep

  1114 our SVN wrangling to a minimum, we won't be merging from a given branch into the

  1115 trunk more than once.

  1116 

  1117 Using branches

  1118 --------------

  1119 

  1120 To use a branch, you'll need to do two things:

  1121 

  1122     * Get the branch's code through Subversion.

  1123 

  1124     * Point your Python ``site-packages`` directory at the branch's version of

  1125       the ``django`` package rather than the version you already have

  1126       installed.

  1127 

  1128 Getting the code from Subversion

  1129 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  1130 

  1131 To get the latest version of a branch's code, check it out using Subversion:

  1132 

  1133 .. code-block:: bash

  1134 

  1135     svn co http://code.djangoproject.com/svn/django/branches/<branch>/

  1136