PageRenderTime 157ms CodeModel.GetById 101ms app.highlight 8ms RepoModel.GetById 32ms app.codeStats 0ms

/docs/internals/contributing.txt

https://code.google.com/p/mango-py/
Plain Text | 1377 lines | 998 code | 379 blank | 0 comment | 0 complexity | 86b9f6ac43d980a4071fd7a295f21223 MD5 | raw file

Large files files are truncated, but you can click here to view the full file

   1======================
   2Contributing to Django
   3======================
   4
   5If you think working *with* Django is fun, wait until you start working *on*
   6it. We're passionate about helping Django users make the jump to contributing
   7members of the community, so there are many ways you can help Django's
   8development:
   9
  10    * Blog about Django. We syndicate all the Django blogs we know about on
  11      the `community page`_; contact jacob@jacobian.org if you've got a blog
  12      you'd like to see on that page.
  13
  14    * Report bugs and request features in our `ticket tracker`_. Please read
  15      `Reporting bugs`_, below, for the details on how we like our bug reports
  16      served up.
  17
  18    * Submit patches for new and/or fixed behavior. Please read `Submitting
  19      patches`_, below, for details on how to submit a patch. If you're looking
  20      for an easy way to start contributing to Django have a look at the
  21      `easy-pickings`_ tickets.
  22
  23    * Join the `django-developers`_ mailing list and share your ideas for how
  24      to improve Django. We're always open to suggestions, although we're
  25      likely to be skeptical of large-scale suggestions without some code to
  26      back it up.
  27
  28    * Triage patches that have been submitted by other users. Please read
  29      `Ticket triage`_ below, for details on the triage process.
  30
  31That's all you need to know if you'd like to join the Django development
  32community. The rest of this document describes the details of how our community
  33works and how it handles bugs, mailing lists, and all the other minutiae of
  34Django development.
  35
  36.. seealso::
  37
  38    This document contains specific details for contributing to
  39    Django. However, many new contributors find this guide confusing
  40    or intimidating at first. For a simpler introduction
  41    to becoming a contributor please see the :doc:`/howto/contribute` guide.
  42
  43.. _reporting-bugs:
  44
  45Reporting bugs
  46==============
  47
  48Well-written bug reports are *incredibly* helpful. However, there's a certain
  49amount of overhead involved in working with any bug tracking system so your
  50help in keeping our ticket tracker as useful as possible is appreciated. In
  51particular:
  52
  53    * **Do** read the :doc:`FAQ </faq/index>` to see if your issue might
  54      be a well-known question.
  55
  56    * **Do** `search the tracker`_ to see if your issue has already been filed.
  57
  58    * **Do** ask on `django-users`_ *first* if you're not sure if what you're
  59      seeing is a bug.
  60
  61    * **Do** write complete, reproducible, specific bug reports. Include as
  62      much information as you possibly can, complete with code snippets, test
  63      cases, etc. This means including a clear, concise description of the
  64      problem, and a clear set of instructions for replicating the problem.
  65      A minimal example that illustrates the bug in a nice small test case
  66      is the best possible bug report.
  67
  68    * **Don't** use the ticket system to ask support questions. Use the
  69      `django-users`_ list, or the `#django`_ IRC channel for that.
  70
  71    * **Don't** use the ticket system to make large-scale feature requests.
  72      We like to discuss any big changes to Django's core on the
  73      `django-developers`_ list before actually working on them.
  74
  75    * **Don't** reopen issues that have been marked "wontfix". This mark
  76      means that the decision has been made that we can't or won't fix
  77      this particular issue. If you're not sure why, please ask
  78      on `django-developers`_.
  79
  80    * **Don't** use the ticket tracker for lengthy discussions, because they're
  81      likely to get lost. If a particular ticket is controversial, please move
  82      discussion to `django-developers`_.
  83
  84    * **Don't** post to django-developers just to announce that you have filed
  85      a bug report. All the tickets are mailed to another list
  86      (`django-updates`_), which is tracked by developers and interested
  87      community members; we see them as they are filed.
  88
  89.. _django-updates: http://groups.google.com/group/django-updates
  90
  91.. _reporting-security-issues:
  92
  93Reporting security issues
  94=========================
  95
  96Report security issues to security@djangoproject.com. This is a private list
  97only open to long-time, highly trusted Django developers, and its archives are
  98not publicly readable.
  99
 100In the event of a confirmed vulnerability in Django itself, we will take the
 101following actions:
 102
 103    * Acknowledge to the reporter that we've received the report and that a
 104      fix is forthcoming. We'll give a rough timeline and ask the reporter
 105      to keep the issue confidential until we announce it.
 106
 107    * Focus on developing a fix as quickly as possible and produce patches
 108      against the current and two previous releases.
 109
 110    * Determine a go-public date for announcing the vulnerability and the fix.
 111      To try to mitigate a possible "arms race" between those applying the
 112      patch and those trying to exploit the hole, we will not announce
 113      security problems immediately.
 114
 115    * Pre-notify third-party distributors of Django ("vendors"). We will send
 116      these vendor notifications through private email which will include
 117      documentation of the vulnerability, links to the relevant patch(es), and a
 118      request to keep the vulnerability confidential until the official
 119      go-public date.
 120
 121    * Publicly announce the vulnerability and the fix on the pre-determined
 122      go-public date. This will probably mean a new release of Django, but
 123      in some cases it may simply be patches against current releases.
 124
 125Submitting patches
 126==================
 127
 128We're always grateful for patches to Django's code. Indeed, bug reports
 129with associated patches will get fixed *far* more quickly than those
 130without patches.
 131
 132"Claiming" tickets
 133------------------
 134
 135In an open-source project with hundreds of contributors around the world, it's
 136important to manage communication efficiently so that work doesn't get
 137duplicated and contributors can be as effective as possible. Hence, our policy
 138is for contributors to "claim" tickets in order to let other developers know
 139that a particular bug or feature is being worked on.
 140
 141If you have identified a contribution you want to make and you're capable of
 142fixing it (as measured by your coding ability, knowledge of Django internals
 143and time availability), claim it by following these steps:
 144
 145    * `Create an account`_ to use in our ticket system.
 146
 147    * If a ticket for this issue doesn't exist yet, create one in our
 148      `ticket tracker`_.
 149
 150    * If a ticket for this issue already exists, make sure nobody else has
 151      claimed it. To do this, look at the "Assigned to" section of the ticket.
 152      If it's assigned to "nobody," then it's available to be claimed.
 153      Otherwise, somebody else is working on this ticket, and you either find
 154      another bug/feature to work on, or contact the developer working on the
 155      ticket to offer your help.
 156
 157    * Log into your account, if you haven't already, by clicking "Login" in the
 158      upper right of the ticket page.
 159
 160    * Claim the ticket by clicking the radio button next to "Accept ticket"
 161      near the bottom of the page, then clicking "Submit changes."
 162
 163If you have an account but have forgotten your password, you can reset it
 164using the `password reset page`_.
 165
 166.. _Create an account: http://www.djangoproject.com/accounts/register/
 167.. _password reset page: http://www.djangoproject.com/accounts/password/reset/
 168
 169Ticket claimers' responsibility
 170~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 171
 172Once you've claimed a ticket, you have a responsibility to work on that ticket
 173in a reasonably timely fashion. If you don't have time to work on it, either
 174unclaim it or don't claim it in the first place!
 175
 176If there's no sign of progress on a particular claimed ticket for a week or
 177two, another developer may ask you to relinquish the ticket claim so that it's
 178no longer monopolized and somebody else can claim it.
 179
 180If you've claimed a ticket and it's taking a long time (days or weeks) to code,
 181keep everybody updated by posting comments on the ticket. If you don't provide
 182regular updates, and you don't respond to a request for a progress report,
 183your claim on the ticket may be revoked. As always, more communication is
 184better than less communication!
 185
 186Which tickets should be claimed?
 187~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 188
 189Of course, going through the steps of claiming tickets is overkill in some
 190cases. In the case of small changes, such as typos in the documentation or
 191small bugs that will only take a few minutes to fix, you don't need to jump
 192through the hoops of claiming tickets. Just submit your patch and be done with
 193it.
 194
 195Patch style
 196-----------
 197
 198    * Make sure your code matches our `coding style`_.
 199
 200    * Submit patches in the format returned by the ``svn diff`` command.
 201      An exception is for code changes that are described more clearly in
 202      plain English than in code. Indentation is the most common example; it's
 203      hard to read patches when the only difference in code is that it's
 204      indented.
 205
 206      Patches in ``git diff`` format are also acceptable.
 207
 208    * When creating patches, always run ``svn diff`` from the top-level
 209      ``trunk`` directory -- i.e., the one that contains ``django``, ``docs``,
 210      ``tests``, ``AUTHORS``, etc. This makes it easy for other people to
 211      apply your patches.
 212
 213    * Attach patches to a ticket in the `ticket tracker`_, using the "attach
 214      file" button. Please *don't* put the patch in the ticket description
 215      or comment unless it's a single line patch.
 216
 217    * Name the patch file with a ``.diff`` extension; this will let the ticket
 218      tracker apply correct syntax highlighting, which is quite helpful.
 219
 220    * Check the "Has patch" box on the ticket details. This will make it
 221      obvious that the ticket includes a patch, and it will add the ticket to
 222      the `list of tickets with patches`_.
 223
 224    * The code required to fix a problem or add a feature is an essential part
 225      of a patch, but it is not the only part. A good patch should also include
 226      a regression test to validate the behavior that has been fixed
 227      (and prevent the problem from arising again).
 228
 229    * If the code associated with a patch adds a new feature, or modifies
 230      behavior of an existing feature, the patch should also contain
 231      documentation.
 232
 233Non-trivial patches
 234-------------------
 235
 236A "non-trivial" patch is one that is more than a simple bug fix. It's a patch
 237that introduces Django functionality and makes some sort of design decision.
 238
 239If you provide a non-trivial patch, include evidence that alternatives have
 240been discussed on `django-developers`_. If you're not sure whether your patch
 241should be considered non-trivial, just ask.
 242
 243Ticket triage
 244=============
 245
 246Unfortunately, not all bug reports in the `ticket tracker`_ provide all
 247the `required details`_. A number of tickets have patches, but those patches
 248don't meet all the requirements of a `good patch`_.
 249
 250One way to help out is to *triage* bugs that have been reported by other
 251users. The core team--as well as many community members--work on this
 252regularly, but more help is always appreciated.
 253
 254Most of the workflow is based around the concept of a ticket's "triage stage".
 255This stage describes where in its lifetime a given ticket is at any time.
 256Along with a handful of flags, this field easily tells us what and who each
 257ticket is waiting on.
 258
 259Since a picture is worth a thousand words, let's start there:
 260
 261.. image:: _images/djangotickets.png
 262   :height: 451
 263   :width: 590
 264   :alt: Django's ticket workflow
 265
 266We've got two roles in this diagram:
 267
 268    * Core developers: people with commit access who are responsible for
 269      making the big decisions, writing large portions of the code and
 270      integrating the contributions of the community.
 271
 272    * Ticket triagers: anyone in the Django community who chooses to
 273      become involved in Django's development process. Our Trac installation
 274      is :ref:`intentionally left open to the public
 275      <the-spirit-of-contributing>`, and anyone can triage tickets.
 276      Django is a community project, and we encourage `triage by the
 277      community`_.
 278
 279Triage stages
 280-------------
 281
 282Second, note the five triage stages:
 283
 284    1. A ticket starts as **Unreviewed**, meaning that nobody has examined
 285       the ticket.
 286
 287    2. **Design decision needed** means "this concept requires a design
 288       decision," which should be discussed either in the ticket comments or on
 289       `django-developers`_. The "Design decision needed" step will generally
 290       only be used for feature requests. It can also be used for issues
 291       that *might* be bugs, depending on opinion or interpretation. Obvious
 292       bugs (such as crashes, incorrect query results, or non-compliance with a
 293       standard) skip this step and move straight to "Accepted".
 294
 295    3. Once a ticket is ruled to be approved for fixing, it's moved into the
 296       **Accepted** stage. This stage is where all the real work gets done.
 297
 298    4. In some cases, a ticket might get moved to the **Someday/Maybe** state.
 299       This means the ticket is an enhancement request that we might consider
 300       adding to the framework if an excellent patch is submitted. These
 301       tickets are not a high priority.
 302
 303    5. If a ticket has an associated patch (see below), it will be reviewed
 304       by the community. If the patch is complete, it'll be marked as **Ready
 305       for checkin** so that a core developer knows to review and commit the
 306       patch.
 307
 308The second part of this workflow involves a set of flags the describe what the
 309ticket has or needs in order to be "ready for checkin":
 310
 311    "Has patch"
 312        This means the ticket has an associated patch_. These will be
 313        reviewed to see if the patch is "good".
 314
 315    "Needs documentation"
 316        This flag is used for tickets with patches that need associated
 317        documentation. Complete documentation of features is a prerequisite
 318        before we can check them into the codebase.
 319
 320    "Needs tests"
 321        This flags the patch as needing associated unit tests. Again, this is a
 322        required part of a valid patch.
 323
 324    "Patch needs improvement"
 325        This flag means that although the ticket *has* a patch, it's not quite
 326        ready for checkin. This could mean the patch no longer applies
 327        cleanly, there is a flaw in the implementation, or that the code
 328        doesn't meet our standards.
 329
 330.. seealso::
 331
 332    The :ref:`contributing howto guide <triage-stages-explained>` has a detailed
 333    explanation of each of the triage stages and how the triage process works in
 334    Trac.
 335
 336.. _ticket-resolutions:
 337
 338Ticket Resolutions
 339------------------
 340
 341A ticket can be resolved in a number of ways:
 342
 343    "fixed"
 344        Used by the core developers once a patch has been rolled into
 345        Django and the issue is fixed.
 346
 347    "invalid"
 348        Used if the ticket is found to be incorrect. This means that the
 349        issue in the ticket is actually the result of a user error, or
 350        describes a problem with something other than Django, or isn't
 351        a bug report or feature request at all (for example, some new users
 352        submit support queries as tickets).
 353
 354    "wontfix"
 355        Used when a core developer decides that this request is not
 356        appropriate for consideration in Django. This is usually chosen after
 357        discussion in the ``django-developers`` mailing list. Feel free to
 358        start or join in discussions of "wontfix" tickets on the mailing list,
 359        but please do not reopen tickets closed as "wontfix" by core
 360        developers.
 361
 362    "duplicate"
 363        Used when another ticket covers the same issue. By closing duplicate
 364        tickets, we keep all the discussion in one place, which helps everyone.
 365
 366    "worksforme"
 367        Used when the ticket doesn't contain enough detail to replicate
 368        the original bug.
 369
 370    "needsinfo"
 371        Used when the ticket does not contain enough information to replicate
 372        the reported issue but is potentially still valid. The ticket
 373        should be reopened when more information is supplied.
 374
 375If you believe that the ticket was closed in error -- because you're
 376still having the issue, or it's popped up somewhere else, or the triagers have
 377made a mistake -- please reopen the ticket and provide further information.
 378Please do not reopen tickets that have been marked as "wontfix" by core
 379developers.
 380
 381.. seealso::
 382
 383    For more information on what to do when closing a ticket, please see the
 384    :ref:`contributing howto guide <closing-tickets>`.
 385
 386.. _required details: `Reporting bugs`_
 387.. _good patch: `Patch style`_
 388.. _triage by the community: `Triage by the general community`_
 389.. _patch: `Submitting patches`_
 390
 391Triage by the general community
 392-------------------------------
 393
 394Although the core developers make the big decisions in the ticket triage
 395process, there's a lot that general community members can do to help the
 396triage process. In particular, you can help out by:
 397
 398    * Closing "Unreviewed" tickets as "invalid", "worksforme" or "duplicate."
 399
 400    * Promoting "Unreviewed" tickets to "Design decision needed" if a design
 401      decision needs to be made, or "Accepted" in case of obvious bugs.
 402
 403    * Correcting the "Needs tests", "Needs documentation", or "Has patch"
 404      flags for tickets where they are incorrectly set.
 405
 406    * Adding the `easy-pickings`_ keyword to tickets that are small and
 407      relatively straightforward.
 408
 409    * Checking that old tickets are still valid. If a ticket hasn't seen
 410      any activity in a long time, it's possible that the problem has been
 411      fixed but the ticket hasn't yet been closed.
 412
 413    * Contacting the owners of tickets that have been claimed but have not
 414      seen any recent activity. If the owner doesn't respond after a week
 415      or so, remove the owner's claim on the ticket.
 416
 417    * Identifying trends and themes in the tickets. If there a lot of bug
 418      reports about a particular part of Django, it may indicate we should
 419      consider refactoring that part of the code. If a trend is emerging,
 420      you should raise it for discussion (referencing the relevant tickets)
 421      on `django-developers`_.
 422
 423However, we do ask the following of all general community members working in
 424the ticket database:
 425
 426    * Please **don't** close tickets as "wontfix." The core developers will
 427      make the final determination of the fate of a ticket, usually after
 428      consultation with the community.
 429
 430    * Please **don't** promote your own tickets to "Ready for checkin". You
 431      may mark other people's tickets which you've reviewed as "Ready for
 432      checkin", but you should get at minimum one other community member to
 433      review a patch that you submit.
 434
 435    * Please **don't** reverse a decision that has been made by a core
 436      developer. If you disagree with a decision that has been made,
 437      please post a message to `django-developers`_.
 438
 439    * If you're unsure if you should be making a change, don't make the change
 440      but instead leave a comment with your concerns on the ticket, or
 441      post a message to `django-developers`_. It's okay to be unsure, but
 442      your input is still valuable.
 443
 444.. _contributing-translations:
 445
 446Submitting and maintaining translations
 447=======================================
 448
 449Various parts of Django, such as the admin site and validation error messages,
 450are internationalized. This means they display different text depending on a
 451user's language setting. For this, Django uses the same internationalization
 452infrastructure available to Django applications described in the
 453:doc:`i18n documentation</topics/i18n/index>`.
 454
 455These translations are contributed by Django users worldwide. If you find an
 456incorrect translation or want to discuss specific translations, go to the
 457`translation team`_ page for that language. If you would like to help out
 458with translating or add a language that isn't yet translated, here's what
 459to do:
 460
 461    * Join the `Django i18n mailing list`_ and introduce yourself.
 462
 463    * Make sure you read the notes about :ref:`specialties-of-django-i18n`.
 464
 465    * Signup at `Transifex`_ and visit the `Django project page`_.
 466
 467    * On the "`Translation Teams`_" page, choose the language team you want
 468      to work with, **or** -- in case the language team doesn't exist yet --
 469      request a new team by clicking on the "Request a new team" button
 470      and select the appropriate language.
 471
 472    * Then, click the "Join this Team" button to become a member of this team.
 473      Every team has at least one coordinator who is responsible to review
 474      your membership request. You can of course also contact the team
 475      coordinator to clarify procedural problems and handle the actual
 476      translation process.
 477
 478    * Once you are a member of a team choose the translation resource you
 479      want update on the team page. For example the "core" resource refers
 480      to the translation catalogue that contains all non-app translations.
 481      Each of the contrib apps also have a resource (prefixed with "contrib-").
 482
 483      .. note::
 484         For more information about how to use Transifex, see the
 485         `Transifex Help`_
 486
 487    * Optionally, review and update the ``conf/locale/<locale>/formats.py``
 488      file to describe the date, time and numbers formatting particularities
 489      of your locale. These files aren't covered by the use of Transifex and
 490      require a patch against the Django source tree, just as a code change
 491      would:
 492
 493      * Create a diff against the current Subversion trunk.
 494
 495      * Open a ticket in Django's ticket system, set its ``Component`` field
 496        to ``Translations``, and attach the patch to it. See
 497        :ref:`format-localization` for details.
 498
 499.. _Django i18n mailing list: http://groups.google.com/group/django-i18n/
 500.. _Transifex: http://www.transifex.net/
 501.. _Django project page: http://www.transifex.net/projects/p/django/
 502.. _translation teams: http://www.transifex.net/projects/p/django/teams/
 503.. _translation team: http://www.transifex.net/projects/p/django/teams/
 504.. _Transifex Help: http://help.transifex.net/
 505
 506Submitting javascript patches
 507=============================
 508
 509.. versionadded:: 1.2
 510
 511Django's admin system leverages the jQuery framework to increase the
 512capabilities of the admin interface. In conjunction, there is an emphasis on
 513admin javascript performance and minimizing overall admin media file size.
 514Serving compressed or "minified" versions of javascript files is considered
 515best practice in this regard.
 516
 517To that end, patches for javascript files should include both the original
 518code for future development (e.g. "foo.js"), and a compressed version for
 519production use (e.g. "foo.min.js"). Any links to the file in the codebase
 520should point to the compressed version.
 521
 522To simplify the process of providing optimized javascript code, Django
 523includes a handy script which should be used to create a "minified" version.
 524This script is located at ``/contrib/admin/media/js/compress.py``.
 525
 526Behind the scenes, ``compress.py`` is a front-end for Google's
 527`Closure Compiler`_ which is written in Java. However, the Closure Compiler
 528library is not bundled with Django directly, so those wishing to contribute
 529complete javascript patches will need to download and install the library
 530independently.
 531
 532The Closure Compiler library requires Java version 6 or higher (Java 1.6 or
 533higher on Mac OS X). Note that Mac OS X 10.5 and earlier did not ship with Java
 5341.6 by default, so it may be necessary to upgrade your Java installation before
 535the tool will be functional. Also note that even after upgrading Java, the
 536default `/usr/bin/java` command may remain linked to the previous Java
 537binary, so relinking that command may be necessary as well.
 538
 539Please don't forget to run ``compress.py`` and include the ``diff`` of the
 540minified scripts when submitting patches for Django's javascript.
 541
 542.. _Closure Compiler: http://code.google.com/closure/compiler/
 543
 544Django conventions
 545==================
 546
 547Various Django-specific code issues are detailed in this section.
 548
 549Use of ``django.conf.settings``
 550-------------------------------
 551
 552Modules should not in general use settings stored in ``django.conf.settings``
 553at the top level (i.e. evaluated when the module is imported). The explanation
 554for this is as follows:
 555
 556Manual configuration of settings (i.e. not relying on the
 557``DJANGO_SETTINGS_MODULE`` environment variable) is allowed and possible as
 558follows::
 559
 560    from django.conf import settings
 561
 562    settings.configure({}, SOME_SETTING='foo')
 563
 564However, if any setting is accessed before the ``settings.configure`` line,
 565this will not work. (Internally, ``settings`` is a ``LazyObject`` which
 566configures itself automatically when the settings are accessed if it has not
 567already been configured).
 568
 569So, if there is a module containing some code as follows::
 570
 571    from django.conf import settings
 572    from django.core.urlresolvers import get_callable
 573
 574    default_foo_view = get_callable(settings.FOO_VIEW)
 575
 576...then importing this module will cause the settings object to be configured.
 577That means that the ability for third parties to import the module at the top
 578level is incompatible with the ability to configure the settings object
 579manually, or makes it very difficult in some circumstances.
 580
 581Instead of the above code, a level of laziness or indirection must be used,
 582such as `django.utils.functional.LazyObject``, ``django.utils.functional.lazy``
 583or ``lambda``.
 584
 585Coding style
 586============
 587
 588Please follow these coding standards when writing code for inclusion in Django:
 589
 590    * Unless otherwise specified, follow :pep:`8`.
 591
 592      You could use a tool like `pep8.py`_ to check for some problems in this
 593      area, but remember that PEP 8 is only a guide, so respect the style of
 594      the surrounding code as a primary goal.
 595
 596    * Use four spaces for indentation.
 597
 598    * Use underscores, not camelCase, for variable, function and method names
 599      (i.e. ``poll.get_unique_voters()``, not ``poll.getUniqueVoters``).
 600
 601    * Use ``InitialCaps`` for class names (or for factory functions that
 602      return classes).
 603
 604    * Mark all strings for internationalization; see the :doc:`i18n
 605      documentation </topics/i18n/index>` for details.
 606
 607    * In docstrings, use "action words" such as::
 608
 609          def foo():
 610              """
 611              Calculates something and returns the result.
 612              """
 613              pass
 614
 615      Here's an example of what not to do::
 616
 617          def foo():
 618              """
 619              Calculate something and return the result.
 620              """
 621              pass
 622
 623    * Please don't put your name in the code you contribute. Our policy is to
 624      keep contributors' names in the ``AUTHORS`` file distributed with Django
 625      -- not scattered throughout the codebase itself. Feel free to include a
 626      change to the ``AUTHORS`` file in your patch if you make more than a
 627      single trivial change.
 628
 629Template style
 630--------------
 631
 632    * In Django template code, put one (and only one) space between the curly
 633      brackets and the tag contents.
 634
 635      Do this:
 636
 637      .. code-block:: html+django
 638
 639          {{ foo }}
 640
 641      Don't do this:
 642
 643      .. code-block:: html+django
 644
 645          {{foo}}
 646
 647View style
 648----------
 649
 650    * In Django views, the first parameter in a view function should be called
 651      ``request``.
 652
 653      Do this::
 654
 655          def my_view(request, foo):
 656              # ...
 657
 658      Don't do this::
 659
 660          def my_view(req, foo):
 661              # ...
 662
 663Model style
 664-----------
 665
 666    * Field names should be all lowercase, using underscores instead of
 667      camelCase.
 668
 669      Do this::
 670
 671          class Person(models.Model):
 672              first_name = models.CharField(max_length=20)
 673              last_name = models.CharField(max_length=40)
 674
 675      Don't do this::
 676
 677          class Person(models.Model):
 678              FirstName = models.CharField(max_length=20)
 679              Last_Name = models.CharField(max_length=40)
 680
 681    * The ``class Meta`` should appear *after* the fields are defined, with
 682      a single blank line separating the fields and the class definition.
 683
 684      Do this::
 685
 686          class Person(models.Model):
 687              first_name = models.CharField(max_length=20)
 688              last_name = models.CharField(max_length=40)
 689
 690              class Meta:
 691                  verbose_name_plural = 'people'
 692
 693      Don't do this::
 694
 695          class Person(models.Model):
 696              first_name = models.CharField(max_length=20)
 697              last_name = models.CharField(max_length=40)
 698              class Meta:
 699                  verbose_name_plural = 'people'
 700
 701      Don't do this, either::
 702
 703          class Person(models.Model):
 704              class Meta:
 705                  verbose_name_plural = 'people'
 706
 707              first_name = models.CharField(max_length=20)
 708              last_name = models.CharField(max_length=40)
 709
 710    * The order of model inner classes and standard methods should be as
 711      follows (noting that these are not all required):
 712
 713        * All database fields
 714        * Custom manager attributes
 715        * ``class Meta``
 716        * ``def __unicode__()``
 717        * ``def __str__()``
 718        * ``def save()``
 719        * ``def get_absolute_url()``
 720        * Any custom methods
 721
 722    * If ``choices`` is defined for a given model field, define the choices as
 723      a tuple of tuples, with an all-uppercase name, either near the top of the
 724      model module or just above the model class. Example::
 725
 726          GENDER_CHOICES = (
 727              ('M', 'Male'),
 728              ('F', 'Female'),
 729          )
 730
 731Documentation style
 732===================
 733
 734We place a high importance on consistency and readability of documentation.
 735(After all, Django was created in a journalism environment!)
 736
 737How to document new features
 738----------------------------
 739
 740We treat our documentation like we treat our code: we aim to improve it as
 741often as possible. This section explains how writers can craft their
 742documentation changes in the most useful and least error-prone ways.
 743
 744Documentation changes come in two forms:
 745
 746    * General improvements -- Typo corrections, error fixes and better
 747      explanations through clearer writing and more examples.
 748
 749    * New features -- Documentation of features that have been added to the
 750      framework since the last release.
 751
 752Our policy is:
 753
 754    **All documentation of new features should be written in a way that clearly
 755    designates the features are only available in the Django development
 756    version. Assume documentation readers are using the latest release, not the
 757    development version.**
 758
 759Our preferred way for marking new features is by prefacing the features'
 760documentation with: ".. versionadded:: X.Y", followed by an optional one line
 761comment and a mandatory blank line.
 762
 763General improvements, or other changes to the APIs that should be emphasized
 764should use the ".. versionchanged:: X.Y" directive (with the same format as the
 765``versionadded`` mentioned above.
 766
 767There's a full page of information about the :doc:`Django documentation
 768system </internals/documentation>` that you should read prior to working on the
 769documentation.
 770
 771Guidelines for reST files
 772-------------------------
 773
 774These guidelines regulate the format of our reST documentation:
 775
 776    * In section titles, capitalize only initial words and proper nouns.
 777
 778    * Wrap the documentation at 80 characters wide, unless a code example
 779      is significantly less readable when split over two lines, or for another
 780      good reason.
 781
 782Commonly used terms
 783-------------------
 784
 785Here are some style guidelines on commonly used terms throughout the
 786documentation:
 787
 788    * **Django** -- when referring to the framework, capitalize Django. It is
 789      lowercase only in Python code and in the djangoproject.com logo.
 790
 791    * **e-mail** -- it has a hyphen.
 792
 793    * **MySQL**
 794
 795    * **PostgreSQL**
 796
 797    * **Python** -- when referring to the language, capitalize Python.
 798
 799    * **realize**, **customize**, **initialize**, etc. -- use the American
 800      "ize" suffix, not "ise."
 801
 802    * **SQLite**
 803
 804    * **subclass** -- it's a single word without a hyphen, both as a verb
 805      ("subclass that model") and as a noun ("create a subclass").
 806
 807    * **Web**, **World Wide Web**, **the Web** -- note Web is always
 808      capitalized when referring to the World Wide Web.
 809
 810    * **Web site** -- use two words, with Web capitalized.
 811
 812Django-specific terminology
 813---------------------------
 814
 815    * **model** -- it's not capitalized.
 816
 817    * **template** -- it's not capitalized.
 818
 819    * **URLconf** -- use three capitalized letters, with no space before
 820      "conf."
 821
 822    * **view** -- it's not capitalized.
 823
 824Committing code
 825===============
 826
 827Please follow these guidelines when committing code to Django's Subversion
 828repository:
 829
 830    * For any medium-to-big changes, where "medium-to-big" is according to your
 831      judgment, please bring things up on the `django-developers`_ mailing list
 832      before making the change.
 833
 834      If you bring something up on `django-developers`_ and nobody responds,
 835      please don't take that to mean your idea is great and should be
 836      implemented immediately because nobody contested it. Django's lead
 837      developers don't have a lot of time to read mailing-list discussions
 838      immediately, so you may have to wait a couple of days before getting a
 839      response.
 840
 841    * Write detailed commit messages in the past tense, not present tense.
 842
 843          * Good: "Fixed Unicode bug in RSS API."
 844          * Bad: "Fixes Unicode bug in RSS API."
 845          * Bad: "Fixing Unicode bug in RSS API."
 846
 847    * For commits to a branch, prefix the commit message with the branch name.
 848      For example: "magic-removal: Added support for mind reading."
 849
 850    * Limit commits to the most granular change that makes sense. This means,
 851      use frequent small commits rather than infrequent large commits. For
 852      example, if implementing feature X requires a small change to library Y,
 853      first commit the change to library Y, then commit feature X in a separate
 854      commit. This goes a *long way* in helping all core Django developers
 855      follow your changes.
 856
 857    * Separate bug fixes from feature changes.
 858
 859      Bug fixes need to be added to the current bugfix branch (e.g. the
 860      ``1.0.X`` branch) as well as the current trunk.
 861
 862    * If your commit closes a ticket in the Django `ticket tracker`_, begin
 863      your commit message with the text "Fixed #abc", where "abc" is the number
 864      of the ticket your commit fixes. Example: "Fixed #123 -- Added support
 865      for foo". We've rigged Subversion and Trac so that any commit message
 866      in that format will automatically close the referenced ticket and post a
 867      comment to it with the full commit message.
 868
 869      If your commit closes a ticket and is in a branch, use the branch name
 870      first, then the "Fixed #abc." For example:
 871      "magic-removal: Fixed #123 -- Added whizbang feature."
 872
 873      For the curious: We're using a `Trac post-commit hook`_ for this.
 874
 875      .. _Trac post-commit hook: http://trac.edgewall.org/browser/trunk/contrib/trac-post-commit-hook
 876
 877    * If your commit references a ticket in the Django `ticket tracker`_ but
 878      does *not* close the ticket, include the phrase "Refs #abc", where "abc"
 879      is the number of the ticket your commit references. We've rigged
 880      Subversion and Trac so that any commit message in that format will
 881      automatically post a comment to the appropriate ticket.
 882
 883Reverting commits
 884-----------------
 885
 886Nobody's perfect; mistakes will be committed. When a mistaken commit is
 887discovered, please follow these guidelines:
 888
 889    * Try very hard to ensure that mistakes don't happen. Just because we
 890      have a reversion policy doesn't relax your responsibility to aim for
 891      the highest quality possible. Really: double-check your work before
 892      you commit it in the first place!
 893
 894    * If possible, have the original author revert his/her own commit.
 895
 896    * Don't revert another author's changes without permission from the
 897      original author.
 898
 899    * If the original author can't be reached (within a reasonable amount
 900      of time -- a day or so) and the problem is severe -- crashing bug,
 901      major test failures, etc -- then ask for objections on django-dev
 902      then revert if there are none.
 903
 904    * If the problem is small (a feature commit after feature freeze,
 905      say), wait it out.
 906
 907    * If there's a disagreement between the committer and the
 908      reverter-to-be then try to work it out on the `django-developers`_
 909      mailing list. If an agreement can't be reached then it should
 910      be put to a vote.
 911
 912    * If the commit introduced a confirmed, disclosed security
 913      vulnerability then the commit may be reverted immediately without
 914      permission from anyone.
 915
 916    * The release branch maintainer may back out commits to the release
 917      branch without permission if the commit breaks the release branch.
 918
 919.. _unit-tests:
 920
 921Unit tests
 922==========
 923
 924Django comes with a test suite of its own, in the ``tests`` directory of the
 925Django tarball. It's our policy to make sure all tests pass at all times.
 926
 927The tests cover:
 928
 929    * Models and the database API (``tests/modeltests/``).
 930    * Everything else in core Django code (``tests/regressiontests``)
 931    * Contrib apps (``django/contrib/<contribapp>/tests``, see below)
 932
 933We appreciate any and all contributions to the test suite!
 934
 935The Django tests all use the testing infrastructure that ships with Django for
 936testing applications. See :doc:`Testing Django applications </topics/testing>`
 937for an explanation of how to write new tests.
 938
 939.. _running-unit-tests:
 940
 941Running the unit tests
 942----------------------
 943
 944Quickstart
 945~~~~~~~~~~
 946
 947Running the tests requires a Django settings module that defines the
 948databases to use. To make it easy to get started. Django provides a
 949sample settings module that uses the SQLite database. To run the tests
 950with this sample ``settings`` module, ``cd`` into the Django
 951``tests/`` directory and run:
 952
 953.. code-block:: bash
 954
 955    ./runtests.py --settings=test_sqlite
 956
 957If you get an ``ImportError: No module named django.contrib`` error,
 958you need to add your install of Django to your ``PYTHONPATH``. For
 959more details on how to do this, read `Pointing Python at the new
 960Django version`_ below.
 961
 962Using another ``settings`` module
 963~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 964
 965The included settings module allows you to run the test suite using
 966SQLite. If you want to test behavior using a different database (and
 967if you're proposing patches for Django, it's a good idea to test
 968across databases), you may need to define your own settings file.
 969
 970To run the tests with different settings, ``cd`` to the ``tests/`` directory
 971and type:
 972
 973.. code-block:: bash
 974
 975    ./runtests.py --settings=path.to.django.settings
 976
 977The :setting:`DATABASES` setting in this test settings module needs to define
 978two databases:
 979
 980    * A ``default`` database. This database should use the backend that
 981      you want to use for primary testing
 982
 983    * A database with the alias ``other``. The ``other`` database is
 984      used to establish that queries can be directed to different
 985      databases. As a result, this database can use any backend you
 986      want. It doesn't need to use the same backend as the ``default``
 987      database (although it can use the same backend if you want to).
 988
 989If you're using a backend that isn't SQLite, you will need to provide other
 990details for each database:
 991
 992    * The :setting:`USER` option for each of your databases needs to
 993      specify an existing user account for the database.
 994
 995    * The :setting:`PASSWORD` option needs to provide the password for
 996      the :setting:`USER` that has been specified.
 997
 998    * The :setting:`NAME` option must be the name of an existing database to
 999      which the given user has permission to connect. The unit tests will not
1000      touch this database; the test runner creates a new database whose name is
1001      :setting:`NAME` prefixed with ``test_``, and this test database is
1002      deleted when the tests are finished. This means your user account needs
1003      permission to execute ``CREATE DATABASE``.
1004
1005You will also need to ensure that your database uses UTF-8 as the default
1006character set. If your database server doesn't use UTF-8 as a default charset,
1007you will need to include a value for ``TEST_CHARSET`` in the settings
1008dictionary for the applicable database.
1009
1010Running only some of the tests
1011~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1012
1013Django's entire test suite takes a while to run, and running every single test
1014could be redundant if, say, you just added a test to Django that you want to
1015run quickly without running everything else. You can run a subset of the unit
1016tests by appending the names of the test modules to ``runtests.py`` on the
1017command line.
1018
1019For example, if you'd like to run tests only for generic relations and
1020internationalization, type:
1021
1022.. code-block:: bash
1023
1024    ./runtests.py --settings=path.to.settings generic_relations i18n
1025
1026How do you find out the names of individual tests? Look in ``tests/modeltests``
1027and ``tests/regressiontests`` -- each directory name there is the name of a
1028test.
1029
1030If you just want to run a particular class of tests, you can specify a list of
1031paths to individual test classes. For example, to run the ``TranslationTests``
1032of the ``i18n`` module, type:
1033
1034.. code-block:: bash
1035
1036    ./runtests.py --settings=path.to.settings i18n.TranslationTests
1037
1038Going beyond that, you can specify an individual test method like this:
1039
1040.. code-block:: bash
1041
1042    ./runtests.py --settings=path.to.settings i18n.TranslationTests.test_lazy_objects
1043
1044Running all the tests
1045~~~~~~~~~~~~~~~~~~~~~
1046
1047If you want to run the full suite of tests, you'll need to install a number of
1048dependencies:
1049
1050    *  PyYAML_
1051    *  Markdown_
1052    *  Textile_
1053    *  Docutils_
1054    *  setuptools_
1055    *  memcached_, plus a :ref:`supported Python binding <memcached>`
1056    *  gettext_ (:ref:`gettext_on_windows`)
1057
1058If you want to test the memcached cache backend, you'll also need to define
1059a :setting:`CACHES` setting that points at your memcached instance.
1060
1061Each of these dependencies is optional. If you're missing any of them, the
1062associated tests will be skipped.
1063
1064.. _PyYAML: http://pyyaml.org/wiki/PyYAML
1065.. _Markdown: http://pypi.python.org/pypi/Markdown/1.7
1066.. _Textile: http://pypi.python.org/pypi/textile
1067.. _docutils: http://pypi.python.org/pypi/docutils/0.4
1068.. _setuptools: http://pypi.python.org/pypi/setuptools/
1069.. _memcached: http://www.danga.com/memcached/
1070.. _gettext: http://www.gnu.org/software/gettext/manual/gettext.html
1071
1072Contrib apps
1073------------
1074
1075Tests for apps in ``django/contrib/`` go in their respective directories under
1076``django/contrib/``, in a ``tests.py`` file. (You can split the tests over
1077multiple modules by using a ``tests`` directory in the normal Python way.)
1078
1079For the tests to be found, a ``models.py`` file must exist (it doesn't
1080have to have anything in it). If you have URLs that need to be
1081mapped, put them in ``tests/urls.py``.
1082
1083To run tests for just one contrib app (e.g. ``markup``), use the same
1084method as above::
1085
1086    ./runtests.py --settings=settings markup
1087
1088Requesting features
1089===================
1090
1091We're always trying to make Django better, and your feature requests are a key
1092part of that. Here are some tips on how to make a request most effectively:
1093
1094    * Request the feature on `django-developers`_, not in the ticket tracker.
1095      It'll get read more closely if it's on the mailing list.
1096
1097    * Describe clearly and concisely what the missing feature is and how you'd
1098      like to see it implemented. Include example code (non-functional is OK)
1099      if possible.
1100
1101    * Explain *why* you'd like the feature. In some cases this is obvious, but
1102      since Django is designed to help real developers get real work done,
1103      you'll need to explain it, if it isn't obvious why the feature would be
1104      useful.
1105
1106As with most open-source projects, code talks. If you are willing to write the
1107code for the feature yourself or if (even better) you've already written it,
1108it's much more likely to be accepted. If it's a large feature that might need
1109multiple developers, we're always happy to give you an experimental branch in
1110our repository; see below.
1111
1112Branch policy
1113=============
1114
1115In general, the trunk must be kept stable. People should be able to run
1116production sites against the trunk at any time. Additionally, commits to trunk
1117ought to be as atomic as possible -- smaller changes are better. Thus, large
1118feature changes -- that is, changes too large to be encapsulated in a single
1119patch, or changes that need multiple eyes on them -- must happen on dedicated
1120branches.
1121
1122This means that if you want to work on a large feature -- anything that would
1123take more than a single patch, or requires large-scale refactoring -- you need
1124to do it on a feature branch. Our development process recognizes two options
1125for feature branches:
1126
1127    1. Feature branches using a distributed revision control system like
1128       Git_, Mercurial_, Bazaar_, etc.
1129
1130       If you're familiar with one of these tools, this is probably your best
1131       option since it doesn't require any support or buy-in from the Django
1132       core developers.
1133
1134       However, do keep in mind that Django will continue to use Subversion for
1135       the foreseeable future, and this will naturally limit the recognition of
1136       your branch. Further, if your branch becomes eligible for merging to
1137       trunk you'll need to find a core developer familiar with your DVCS of
1138       choice who'll actually perform the merge.
1139
1140       If you do decided to start a distributed branch of Django and choose to
1141       make it public, please add the branch to the `Django branches`_ wiki
1142       page.
1143
1144    2. Feature branches using SVN have a higher bar. If you want a branch
1145       in SVN itself, you'll need a "mentor" among the :doc:`core committers
1146       </internals/committers>`. This person is responsible for actually
1147       creating the branch, monitoring your process (see below), and
1148       ultimately merging the branch into trunk.
1149
1150       If you want a feature branch in SVN, you'll need to ask in
1151       `django-developers`_ for a mentor.
1152
1153.. _git: http://git-scm.com/
1154.. _mercurial: http://mercurial.selenic.com/
1155.. _bazaar: http://bazaar.canonical.com/
1156.. _django branches: http://code.djangoproject.com/wiki/DjangoBranches
1157
1158Branch rules
1159------------
1160
1161We've got a few rules for branches born out of experience with what makes a
1162successful Django branch.
1163
1164DVCS branches are obviously not under central control, so we have no way of
1165enforcing these rules. However, if you're using a DVCS, following these rules
1166will give you the best chance of having a successful branch (read: merged back
1167to trunk).
1168
1169Developers with branches in SVN, however, **must** follow these rules. The
1170branch mentor will keep on eye on the branch and **will delete it** if these
1171rules are broken.
1172
1173    * Only branch entire copies of the Django tree, even if work is only
1174      happening on part of that tree. This makes it painless to switch to a
1175      branch.
1176
1177    * Merge changes from trunk no less than once a week, and preferably every
1178      couple-three days.
1179
1180      In our experience, doing regular trunk merges is often the difference
1181      between a successful branch and one that fizzles and dies.
1182
1183      If you're working on an SVN branch, you should be using `svnmerge.py`_
1184      to track merges from trunk.
1185
1186    * Keep tests passing and documentation up-to-date. As with patches,
1187      we'll only merge a branch that comes with tests and documentation.
1188
1189.. _svnmerge.py: http://www.orcaware.com/svn/wiki/Svnmerge.py
1190
1191Once the branch is stable and ready to be merged into the trunk, alert
1192`django-developers`_.
1193
1194After a branch has been merged, it should be considered "dead"; write access to
1195it will be disabled, and old branches will be periodically "trimmed." To keep
1196our SVN wrangling to a minimum, we won't be merging from a given branch into
1197the trunk more than once.
1198
1199Using branches
1200--------------
1201
1202To use a branch, you'll need to do two things:
1203
1204    * Get the branch's code through Subversion.
1205
1206    * Point your Python ``site-packages`` directory at the branch's version of
1207      the ``django`` package rather than the version you already have
1208      installed.
1209
1210Getting the code from Subversion
1211~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1212
1213To get the latest version of a branch's code, check it out using Subversion:
1214
1215.. code-block:: bash
1216
1217    svn co http://code.djangoproject.com/svn/django/branches/<branch>/
1218
1219...where ``<branch>`` is the branch's name. See the `list of branch names`_.
1220
1221Alternatively, you can automatically convert an existing directory of the
1222Django source code as long as you've checked it out via Subversion. To do the
1223conversion, execute this command from within your ``django`` directory:
1224
1225.. code-block:: bash
1226
1227    svn switch http://code.djangoproject.com/svn/django/branches/<branch>/
1228
1229The advantage of using ``svn switch`` instead of ``svn co`` is that the
1230``switch`` command retains any changes you might have made to your local copy
1231of the code. It attempts to merge those changes into the "switched" code. The
1232disadvantage is that it may cause conflicts with your local changes if the
1233"switched" code has altered the same lines of code.
1234
1235(Note that if you use ``svn switch``, you don't need to point Python at the new
1236version, as explained in the next section.)
1237
1238.. _list of branch names: http://code.djangoproject.com/browser/django/branches
1239
1240Pointing Python at the new Django version
1241~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1242
1243Once you've retrieved the branch's code, you'll need to change your Python
1244``site-packages`` directory so that it points to the branch version of the
1245``django`` directory. (The ``site-packages`` directory is somewhere such as
1246``/usr/lib/python2.4/site-packages`` or
1247``/usr/local/lib/python2.4/site-packā€¦

Large files files are truncated, but you can click here to view the full file