======================

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