====================== 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 ` 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`. 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`. * Signup at `Transifex`_ and visit the `Django project page`_. * On the "`Translation Teams`_" page, choose the language team you want to work with, **or** -- in case the language team doesn't exist yet -- request a new team by clicking on the "Request a new team" button and select the appropriate language. * Then, click the "Join this Team" button to become a member of this team. Every team has at least one coordinator who is responsible to review your membership request. You can of course also contact the team coordinator to clarify procedual problems and handle the actual translation process. * Once you are a member of a team choose the translation resource you want update on the team page. For example the "core" resource refers to the translation catalogue that contains all non-app translations. Each of the contrib apps also have a resource -- prefixed with "contrib-". .. note:: For more information about how to use Transifex, see the `Transifex Help`_ * Optionally, review and update the ``conf/locale//formats.py`` file to describe the date, time and numbers formatting particularities of your locale. These files aren't covered by the use of Transifex and require a patch against the Django source tree, just as a code change would: * 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. See :ref:`format-localization` for details. .. _Django i18n mailing list: http://groups.google.com/group/django-i18n/ .. _Transifex: http://www.transifex.net/ .. _Django project page: http://www.transifex.net/projects/p/django/ .. _translation teams: http://www.transifex.net/projects/p/django/teams/ .. _Transifex Help: http://help.transifex.net/ 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 ` 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 ` 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//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 ` 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). As a convenience, a minimal settings file, using two in memory SQLite databases, 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 a :ref:`supported Python binding ` * gettext_ (:ref:`gettext_on_windows`) If you want to test the memcached cache backend, you will also need to define a :setting:`CACHES` 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/ .. _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 `. 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// ...where ```` 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// 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`_ (``.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 # is a svn checkout of: # http://code.djangoproject.com/svn/django/branches// # #/path/to/ # On windows a path may look like this: # C:/path/to/ 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