Ticket #16469: 16469.diff

File 16469.diff, 65.5 KB (added by aaugustin, 4 years ago)
  • docs/internals/contributing/translations.txt

     
    33=======================================
    44
    55Various parts of Django, such as the admin site and validation error messages,
    6 are internationalized. This means they display different text depending on a
    7 user's language setting. For this, Django uses the same internationalization
    8 infrastructure available to Django applications described in the
     6are internationalized. This means they display different text depending on each
     7user's language setting. For this, Django uses the same internationalization and
     8localization infrastructure available to Django applications, described in the
    99:doc:`i18n documentation</topics/i18n/index>`.
    1010
    11 These translations are contributed by Django users worldwide. If you find an
    12 incorrect translation or want to discuss specific translations, go to the
    13 `translation team`_ page for that language. If you would like to help out
    14 with translating or add a language that isn't yet translated, here's what
    15 to do:
     11Internationalization
     12--------------------
    1613
     14Translations are contributed by Django users worldwide. The translation work is
     15coordinated at `Transifex`_.
     16
     17If you find an incorrect translation or want to discuss specific translations,
     18go to the `translation team`_ page for that language. If you would like to help
     19out with translating or add a language that isn't yet translated, here's what to
     20do:
     21
    1722    * Join the `Django i18n mailing list`_ and introduce yourself.
    1823
    1924    * Make sure you read the notes about :ref:`specialties-of-django-i18n`.
    2025
    2126    * Signup at `Transifex`_ and visit the `Django project page`_.
    2227
    23     * On the "`Translation Teams`_" page, choose the language team you want
     28    * On the `translation teams`_ page, choose the language team you want
    2429      to work with, **or** -- in case the language team doesn't exist yet --
    2530      request a new team by clicking on the "Request a new team" button
    2631      and select the appropriate language.
     
    3742      Each of the contrib apps also have a resource (prefixed with "contrib").
    3843
    3944      .. note::
    40          For more information about how to use Transifex, see the
    41          `Transifex Help`_
     45         For more information about how to use Transifex, read the
     46         `Transifex User Guide`_.
    4247
    43     * Optionally, review and update the ``conf/locale/<locale>/formats.py``
    44       file to describe the date, time and numbers formatting particularities
    45       of your locale. These files aren't covered by the use of Transifex and
    46       require a patch against the Django source tree, just as a code change
    47       would:
     48Localization
     49------------
    4850
    49       * Create a diff against the current Subversion trunk.
     51You can also review ``conf/locale/<locale>/formats.py``. This file describes
     52the date, time and numbers formatting particularities of your locale. See
     53:ref:`format-localization` for details.
    5054
    51       * Open a ticket in Django's ticket system, set its ``Component`` field
    52         to ``Translations``, and attach the patch to it. See
    53         :ref:`format-localization` for details.
     55The format files aren't managed by the use of Transifex. To change them, you
     56must :doc:`create a patch<writing-code/submitting-patches>` against the Django source tree, as for any code change:
    5457
     58    * Create a diff against the current Subversion trunk.
     59
     60    * Open a ticket in Django's ticket system, set its ``Component`` field to
     61      ``Translations``, and attach the patch to it.
     62
     63.. _Transifex: http://www.transifex.net/
    5564.. _Django i18n mailing list: http://groups.google.com/group/django-i18n/
    56 .. _Transifex: http://www.transifex.net/
    5765.. _Django project page: http://www.transifex.net/projects/p/django/
     66.. _translation team: http://www.transifex.net/projects/p/django/teams/
    5867.. _translation teams: http://www.transifex.net/projects/p/django/teams/
    59 .. _translation team: http://www.transifex.net/projects/p/django/teams/
    60 .. _Transifex Help: http://help.transifex.net/
     68.. _Transifex User Guide: http://help.transifex.net/
  • docs/internals/contributing/committing-code.txt

     
    2828    in question is likely to be sufficient.
    2929
    3030Decisions on new committers will follow the process explained in
    31 :ref:`how-we-make-decisions`.
     31:ref:`how-we-make-decisions`. To request commit access, please contact an
     32existing committer privately. Public requests for commit access are potential
     33flame-war starters, and will be ignored.
    3234
    33 To request commit access, please contact an existing committer privately.
    34 Public requests for commit access are potential flame-war starters, and
    35 will be ignored.
    36 
    3735Committing guidelines
    3836---------------------
    3937
     
    6967
    7068    * Separate bug fixes from feature changes.
    7169
    72       Bug fixes need to be added to the current bugfix branch (e.g. the
    73       ``1.0.X`` branch) as well as the current trunk.
     70      Bug fixes need to be added to the current bugfix branch as well as the
     71      current trunk.
    7472
    7573    * If your commit closes a ticket in the Django `ticket tracker`_, begin
    7674      your commit message with the text "Fixed #abc", where "abc" is the
    77       number of the ticket your commit fixes. Example: "Fixed #123 -- Adde
     75      number of the ticket your commit fixes. Example: "Fixed #123 -- Added
    7876      support for foo". We've rigged Subversion and Trac so that any commit
    7977      message in that format will automatically close the referenced ticket
    8078      and post a comment to it with the full commit message.
     
    8381      first, then the "Fixed #abc." For example:
    8482      "magic-removal: Fixed #123 -- Added whizbang feature."
    8583
    86       For the curious: We're using a `Trac post-commit hook`_ for this.
     84      For the curious: we're using a `Trac post-commit hook`_ for this.
    8785
    8886      .. _Trac post-commit hook: http://trac.edgewall.org/browser/trunk/contrib/trac-post-commit-hook
    8987
     
    111109
    112110    * If the original author can't be reached (within a reasonable amount
    113111      of time -- a day or so) and the problem is severe -- crashing bug,
    114       major test failures, etc -- then ask for objections on django-dev
    115       then revert if there are none.
     112      major test failures, etc -- then ask for objections on the
     113      `django-developers`_ mailing list then revert if there are none.
    116114
    117115    * If the problem is small (a feature commit after feature freeze,
    118116      say), wait it out.
  • docs/internals/contributing/new-contributors.txt

     
    55New contributor and not sure what to do? Want to help but just don't know how
    66to get started? This is the section for you.
    77
    8 * **Pick a subject area that you care about, that you are familiar with, or
    9   that you want to learn about**
     8First steps
     9-----------
    1010
    11   You don't already have to be an expert on the area you want to work on; you
    12   become an expert through your ongoing contributions to the code.
     11Start with these easy tasks to discover Django's development process.
    1312
    1413* **Triage tickets**
    1514
    16   If a ticket is unreviewed and reports a bug, try and reproduce it. If you
     15  If an `unreviewed ticket`_ reports a bug, try and reproduce it. If you
    1716  can reproduce it and it seems valid, make a note that you confirmed the bug
    1817  and accept the ticket. Make sure the ticket is filed under the correct
    1918  component area. Consider writing a patch that adds a test for the bug's
     
    4443  :doc:`writing-documentation`, in particular the tips for
    4544  :ref:`improving-the-documentation`.
    4645
    47 * **Analyze the ticket's context and history**
     46  .. note::
    4847
     48      The `reports page`_ contains links to many useful Trac queries, including
     49      several that are useful for triaging tickets and reviewing patches as
     50      suggested above.
     51
     52      .. _reports page: http://code.djangoproject.com/wiki/Reports
     53
     54.. _unreviewed ticket: http://code.djangoproject.com/query?status=!closed&stage=Unreviewed
     55
     56
     57Guidelines
     58----------
     59
     60As a newcomer on a large project, it's easy to experience frustration. Here's
     61some advice to make your work on Django more useful and rewarding.
     62
     63* **Pick a subject area that you care about, that you are familiar with, or
     64  that you want to learn about**
     65
     66  You don't already have to be an expert on the area you want to work on; you
     67  become an expert through your ongoing contributions to the code.
     68
     69* **Analyze tickets' context and history**
     70
    4971  Trac isn't an absolute; the context is just as important as the words.
    5072  When reading Trac, you need to take into account who says things, and when
    5173  they were said. Support for an idea two years ago doesn't necessarily mean
     
    96118  writing the very first tests for that feature, not that you get a pass from
    97119  writing tests altogether.
    98120
    99 .. note::
     121.. _easy pickings: http://code.djangoproject.com/query?status=!closed&easy=1
    100122
    101     The `Reports page`_ contains links to many useful Trac queries, including
    102     several that are useful for triaging tickets and reviewing patches as
    103     suggested above.
    104 
    105     .. _Reports page: http://code.djangoproject.com/wiki/Reports
    106 
    107123.. _new-contributors-faq:
    108124
    109125FAQ
     
    114130
    115131   First off, it's not personal. Django is entirely developed by volunteers
    116132   (even the core developers), and sometimes folks just don't have time. The
    117    best thing to do is to send a gentle reminder to the Django Developers
     133   best thing to do is to send a gentle reminder to the django-developers
    118134   mailing list asking for review on the ticket, or to bring it up in the
    119135   #django-dev IRC channel.
    120136
     
    130146   Design Decision Needed requires consensus about the right solution.  At the
    131147   very least it needs consensus among the core developers, and ideally it has
    132148   consensus from the community as well. The best way to accomplish this is to
    133    start a thread on the Django Developers mailing list, and for very complex
     149   start a thread on the django-developers mailing list, and for very complex
    134150   issues to start a wiki page summarizing the problem and the possible
    135151   solutions.
    136 
    137 .. _`easy pickings`: http://code.djangoproject.com/query?status=!closed&easy=1
  • docs/internals/contributing/index.txt

     
    22Contributing to Django
    33======================
    44
     5Django is a community that lives on its volunteers. As it keeps growing, we
     6always need more people to help others. As soon as you learn Django, you can
     7contribute in many ways:
     8
     9    * Join the `django-users`_ mailing list and answer questions. This
     10      mailing list has a huge audience, and we really want to maintain a
     11      friendly and helpful atmosphere. If you're new to the Django community,
     12      you should read the `posting guidelines`_.
     13
     14    * Join the `#django IRC channel`_ on Freenode and answer questions. By
     15      explaining Django to other users, you're going to learn a lot about the
     16      framework yourself.
     17
     18    * Blog about Django. We syndicate all the Django blogs we know about on
     19      the `community page`_; if you'd like to see your blog on that page you
     20      can `register it here`_.
     21
     22    * Contribute to open-source Django projects, write some documentation, or
     23      release your own code as an open-source pluggable application. The
     24      ecosystem of pluggable applications is a big strength of Django, help us
     25      build it!
     26
    527If you think working *with* Django is fun, wait until you start working *on*
    628it. We're passionate about helping Django users make the jump to contributing
    729members of the community, so there are several ways you can help Django's
    830development:
    931
    10     * Blog about Django. We syndicate all the Django blogs we know about on
    11       the `community page`_; if you'd like to see your blog on that page you
    12       can `register it here`_.
     32    * :doc:`Report bugs <bugs-and-features>` in our `ticket tracker`_.
    1333
    14     * :doc:`Report bugs and request features<bugs-and-features>` in our
    15       `ticket tracker`_.
    16 
    1734    * Join the `django-developers`_ mailing list and share your ideas for how
    1835      to improve Django. We're always open to suggestions.
    1936
    20     * :doc:`Submit patches<writing-code/submitting-patches>` for new and/or
     37    * :doc:`Submit patches <writing-code/submitting-patches>` for new and/or
    2138      fixed behavior. If you're looking for an easy way to start contributing
    2239      to Django have a look at the `easy pickings`_ tickets.
    2340
    24     * :doc:`Improve the documentation<writing-documentation>` or
    25       :doc:`write unit tests<writing-code/unit-tests>`.
     41    * :doc:`Improve the documentation <writing-documentation>` or
     42      :doc:`write unit tests <writing-code/unit-tests>`.
    2643
    27     * :doc:`Triage tickets<triaging-tickets>` that have been created by other
    28       users.
     44    * :doc:`Triage tickets and review patches <triaging-tickets>` created by
     45      other users.
    2946
    30 ... and many more ways! Really, **ANYONE** can do something to help make
    31 Django better and greater. Browse the following sections to find out how:
     47Really, **ANYONE** can do something to help make Django better and greater!
    3248
     49Browse the following sections to find out how:
     50
    3351.. toctree::
    3452   :maxdepth: 2
    3553
     
    4159   translations
    4260   committing-code
    4361
     62.. _django-users: http://groups.google.com/group/django-users
     63.. _posting guidelines: https://code.djangoproject.com/wiki/UsingTheMailingList
     64.. _#django IRC channel: irc://irc.freenode.net/django
     65.. _community page: http://www.djangoproject.com/community/
     66.. _register it here: http://www.djangoproject.com/community/add/blogs/
    4467.. _django-developers: http://groups.google.com/group/django-developers
    4568.. _ticket tracker: http://code.djangoproject.com/newticket
    46 .. _community page: http://www.djangoproject.com/community/
    47 .. _`easy pickings`: http://code.djangoproject.com/query?status=!closed&easy=1
    48 .. _`register it here`: http://www.djangoproject.com/community/add/blogs/
     69.. _easy pickings: http://code.djangoproject.com/query?status=!closed&easy=1
  • docs/internals/contributing/triaging-tickets.txt

     
    22Triaging tickets
    33================
    44
    5 Django uses Trac_ for managing our progress, and Trac is a community-tended
    6 garden of the bugs people have found and the features people would like to see
    7 added. As in any garden, sometimes there are weeds to be pulled and sometimes
    8 there are flowers and vegetables that need picking. We need your help to sort
    9 out one from the other, and in the end we all benefit together.
     5Django uses Trac_ for managing the work on the code base. Trac is a
     6community-tended garden of the bugs people have found and the features people
     7would like to see added. As in any garden, sometimes there are weeds to be
     8pulled and sometimes there are flowers and vegetables that need picking. We need
     9your help to sort out one from the other, and in the end we all benefit
     10together.
    1011
    1112Like all gardens, we can aspire to perfection but in reality there's no such
    1213thing. Even in the most pristine garden there are still snails and insects.
    13 In a community garden there are also helpful people who--with the best of
    14 intentions--fertilize the weeds and poison the roses. It's the job of the
     14In a community garden there are also helpful people who -- with the best of
     15intentions -- fertilize the weeds and poison the roses. It's the job of the
    1516community as a whole to self-manage, keep the problems to a minimum, and
    1617educate those coming into the community so that they can become valuable
    1718contributing members.
     
    3940:ref:`good patch<patch-style>`.
    4041
    4142One way to help out is to *triage* tickets that have been created by other
    42 users. The core team--as well as many community members--work on this
    43 regularly, but more help is always appreciated.
     43users. The core team and several community members work on this regularly, but
     44more help is always appreciated.
    4445
    4546Most of the workflow is based around the concept of a ticket's
    4647:ref:`triage stages <triage-stages>`. Each stage describes where in its
     
    146147:ref:`New contributors' FAQ<new-contributors-faq>` for "My ticket has been in
    147148DDN forever! What should I do?"
    148149
    149 This stage will generally only be used for feature
    150 requests. It can also be used for issues that *might* be bugs, depending on
    151 opinion or interpretation. Obvious bugs (such as crashes, incorrect query
    152 results, or non-compliance with a standard) skip this stage and move straight
    153 to "Accepted".
     150This stage will often be used for feature requests. It can also be used for
     151issues that *might* be bugs, depending on opinion or interpretation. Obvious
     152bugs (such as crashes, incorrect query results, or non-compliance with a
     153standard) skip this stage and move straight to "Accepted".
    154154
    155155Ready For Checkin
    156156~~~~~~~~~~~~~~~~~
     
    200200        This flag means that although the ticket *has* a patch, it's not quite
    201201        ready for checkin. This could mean the patch no longer applies
    202202        cleanly, there is a flaw in the implementation, or that the code
    203         doesn't meet our standards."
     203        doesn't meet our standards.
    204204  * Easy pickings
    205205        Tickets that would require small, easy, patches.
    206206
     
    250250  * If there is a way they can improve the ticket to reopen it, let them know.
    251251
    252252  * If the ticket is a duplicate, reference the original ticket. Also
    253     cross-reference the closed ticket by living a comment in the original one
     253    cross-reference the closed ticket by leaving a comment in the original one
    254254    -- this allows to access more related information about the reported bug
    255255    or requested feature.
    256256
     
    279279        discussion in the `django-developers`_ mailing list. Feel free to
    280280        start or join in discussions of "wontfix" tickets on the
    281281        django-developers_ mailing list, but please do not reopen tickets
    282         closed as "wontfix" by core developers.
     282        closed as "wontfix" by a :doc:`core developer</internals/committers>`.
    283283
    284284  * duplicate
    285285        Used when another ticket covers the same issue. By closing duplicate
     
    371371      checkin", but you should get at minimum one other community member to
    372372      review a patch that you submit.
    373373
    374     * Please **don't** reverse a decision that has been made by a core
    375       developer. If you disagree with a decision that has been made,
    376       please post a message to `django-developers`_.
     374    * Please **don't** reverse a decision that has been made by a :doc:`core
     375      developer</internals/committers>`. If you disagree with a decision that
     376      has been made, please post a message to `django-developers`_.
    377377
    378378    * If you're unsure if you should be making a change, don't make the
    379379      change but instead leave a comment with your concerns on the ticket,
  • docs/internals/contributing/writing-documentation.txt

     
    99
    1010Documentation changes generally come in two forms:
    1111
    12     * General improvements -- Typo corrections, error fixes and better
     12    * General improvements: typo corrections, error fixes and better
    1313      explanations through clearer writing and more examples.
    1414
    15     * New features -- Documentation of features that have been added to the
     15    * New features: documentation of features that have been added to the
    1616      framework since the last release.
    1717
    1818This section explains how writers can craft their documentation changes
     
    6161
    6262    * **email** -- no hyphen.
    6363
    64     * **MySQL**
     64    * **MySQL**, **PostgreSQL**, **SQLite**
    6565
    66     * **PostgreSQL**
    67 
    6866    * **Python** -- when referring to the language, capitalize Python.
    6967
    7068    * **realize**, **customize**, **initialize**, etc. -- use the American
    7169      "ize" suffix, not "ise."
    7270
    73     * **SQLite**
    74 
    7571    * **subclass** -- it's a single word without a hyphen, both as a verb
    7672      ("subclass that model") and as a noun ("create a subclass").
    7773
     
    168164
    169165Our policy for new features is:
    170166
    171     **All documentation of new features should be written in a way that
     167    All documentation of new features should be written in a way that
    172168    clearly designates the features are only available in the Django
    173169    development version. Assume documentation readers are using the latest
    174     release, not the development version.**
     170    release, not the development version.
    175171
    176172Our preferred way for marking new features is by prefacing the features'
    177173documentation with: "``.. versionadded:: X.Y``", followed by an optional one
  • docs/internals/contributing/bugs-and-features.txt

     
    22Reporting bugs and requesting features
    33======================================
    44
    5 Before reporting a bug or requesting a new feature please consider these
     5Before reporting a bug or requesting a new feature, please consider these
    66general points:
    77
    88* Check that someone hasn't already filed the bug or feature request by
    99  `searching`_ or running `custom queries`_ in the ticket tracker.
    1010
    1111* Don't use the ticket system to ask support questions. Use the
    12   `django-users`_ list, or the `#django`_ IRC channel for that.
     12  `django-users`_ list or the `#django`_ IRC channel for that.
    1313
    1414* Don't reopen issues that have been marked "wontfix" by a core developer.
    1515  This mark means that the decision has been made that we can't or won't fix
     
    1717  on `django-developers`_.
    1818
    1919* Don't use the ticket tracker for lengthy discussions, because they're
    20   likely to get lost. If a particular ticket is controversial, please move
     20  likely to get lost. If a particular ticket is controversial, please move the
    2121  discussion to `django-developers`_.
    2222
    2323.. _reporting-bugs:
     
    3333    * **Do** read the :doc:`FAQ </faq/index>` to see if your issue might
    3434      be a well-known question.
    3535
    36     * **Do** ask on `django-users`_ *first* if you're not sure if what you're
    37       seeing is a bug.
     36    * **Do** ask on `django-users`_ or `#django`_ *first* if you're not sure if
     37      what you're seeing is a bug.
    3838
    39     * **Do** write complete, reproducible, specific bug reports. Include as
    40       much information as you possibly can, complete with code snippets, test
    41       cases, etc. This means including a clear, concise description of the
    42       problem, and a clear set of instructions for replicating the problem.
    43       A minimal example that illustrates the bug in a nice small test case
    44       is the best possible bug report.
     39    * **Do** write complete, reproducible, specific bug reports. You must
     40      include a clear, concise description of the problem, and a set of
     41      instructions for replicating it. Add as much debug information as you can:
     42      code snippets, test cases, exception backtraces, screenshots, etc. A nice
     43      small test case is the best way to report a bug, as it gives us an easy
     44      way to confirm the bug quickly.
    4545
    46     * **Don't** post to django-developers just to announce that you have filed
    47       a bug report. All the tickets are mailed to another list
    48       (`django-updates`_), which is tracked by developers and interested
     46    * **Don't** post to `django-developers`_ just to announce that you have
     47      filed a bug report. All the tickets are mailed to another list,
     48      `django-updates`_, which is tracked by developers and interested
    4949      community members; we see them as they are filed.
    5050
    5151To understand the lifecycle of your ticket once you have created it, refer to
     
    9595We're always trying to make Django better, and your feature requests are a key
    9696part of that. Here are some tips on how to make a request most effectively:
    9797
    98     * First request the feature on `django-developers`_, not in the ticket
    99       tracker. It'll get read more closely if it's on the mailing list.
     98    * Make sure the feature actually requires changes in Django's core. If your
     99      idea can be developed as an independent application or module — for
     100      instance, you want to support another database engine — we'll probably
     101      suggest that you to develop it independently. Then, if your project
     102      gathers sufficient community support, we may consider it for inclusion in
     103      Django.
    100104
     105    * First request the feature on the `django-developers`_ list, not in the
     106      ticket tracker. It'll get read more closely if it's on the mailing list.
     107      This is even more important for large-scale feature requests. We like to
     108      discuss any big changes to Django's core on the mailing list before
     109      actually working on them.
     110
    101111    * Describe clearly and concisely what the missing feature is and how you'd
    102112      like to see it implemented. Include example code (non-functional is OK)
    103113      if possible.
     
    107117      you'll need to explain it, if it isn't obvious why the feature would be
    108118      useful.
    109119
    110     * Don't use the ticket system to make large-scale feature requests.
    111       We like to discuss any big changes to Django's core on the
    112       `django-developers`_ list before actually working on them.
     120If core developers agree on the feature, then it's appropriate to create a
     121ticket. Include a link the discussion on `django-developers`_ in the ticket
     122description.
    113123
    114124As with most open-source projects, code talks. If you are willing to write the
    115 code for the feature yourself or if (even better) you've already written it,
     125code for the feature yourself or, even better, if you've already written it,
    116126it's much more likely to be accepted. If it's a large feature that might need
    117127multiple developers, we're always happy to give you an experimental branch in
    118128our repository; see the :doc:`writing-code/branch-policy`.
    119129
    120 To understand the lifecycle of your ticket once you have created it, refer to
    121 :doc:`triaging-tickets`.
    122 
    123130See also: :ref:`documenting-new-features`.
    124131
    125132.. _how-we-make-decisions:
     
    141148    * -1: "I strongly disagree and would be very unhappy to see the idea turn
    142149      into reality."
    143150
    144 Although these votes on django-developers are informal, they'll be taken very
    145 seriously. After a suitable voting period, if an obvious consensus arises
    146 we'll follow the votes.
     151Although these votes on `django-developers`_ are informal, they'll be taken very
     152seriously. After a suitable voting period, if an obvious consensus arises we'll
     153follow the votes.
    147154
    148155However, consensus is not always possible. If consensus cannot be reached, or
    149156if the discussion towards a consensus fizzles out without a concrete decision,
     
    175182
    176183
    177184.. _searching: http://code.djangoproject.com/search
    178 .. _`custom queries`: https://code.djangoproject.com/query
     185.. _custom queries: https://code.djangoproject.com/query
    179186.. _django-developers: http://groups.google.com/group/django-developers
    180187.. _django-users: http://groups.google.com/group/django-users
    181 .. _`#django`: irc://irc.freenode.net/django
     188.. _#django: irc://irc.freenode.net/django
  • docs/internals/contributing/writing-code/coding-style.txt

     
    99
    1010    * Unless otherwise specified, follow :pep:`8`.
    1111
    12       You could use a tool like `pep8.py`_ to check for some problems in this
     12      You could use a tool like `pep8`_ to check for some problems in this
    1313      area, but remember that PEP 8 is only a guide, so respect the style of
    1414      the surrounding code as a primary goal.
    1515
     
    171171level is incompatible with the ability to configure the settings object
    172172manually, or makes it very difficult in some circumstances.
    173173
    174 Instead of the above code, a level of laziness or indirection must be used,
    175 such as `django.utils.functional.LazyObject``, ``django.utils.functional.lazy``
    176 or ``lambda``.
     174Instead of the above code, a level of laziness or indirection must be used, such
     175as :class:`django.utils.functional.LazyObject`,
     176:func:`django.utils.functional.lazy` or ``lambda``.
    177177
    178178Miscellaneous
    179179-------------
     
    181181    * Mark all strings for internationalization; see the :doc:`i18n
    182182      documentation </topics/i18n/index>` for details.
    183183
     184    * Remove ``import`` statements that are no longer used when you change code.
     185      The most common tools for this task are `pyflakes`_ and `pylint`_.
     186
    184187    * Please don't put your name in the code you contribute. Our policy is to
    185188      keep contributors' names in the ``AUTHORS`` file distributed with Django
    186189      -- not scattered throughout the codebase itself. Feel free to include a
    187190      change to the ``AUTHORS`` file in your patch if you make more than a
    188191      single trivial change.
    189192
    190 .. _pep8.py: http://pypi.python.org/pypi/pep8/
     193.. _pep8: http://pypi.python.org/pypi/pep8
     194.. _pyflakes: http://pypi.python.org/pypi/pyflakes
     195.. _pylint: http://pypi.python.org/pypi/pylint
  • docs/internals/contributing/writing-code/branch-policy.txt

     
    146146location of the branch's ``django`` package. If you want to switch back, just
    147147change the symlink to point to the old code.
    148148
    149 A third option is to use a `path file`_ (``<something>.pth``) which should
    150 work on all systems (including Windows, which doesn't have symlinks
    151 available). First, make sure there are no files, directories or symlinks named
    152 ``django`` in your ``site-packages`` directory. Then create a text file named
    153 ``django.pth`` and save it to your ``site-packages`` directory. That file
    154 should contain a path to your copy of Django on a single line and optional
    155 comments. Here is an example that points to multiple branches. Just uncomment
    156 the line for the branch you want to use ('Trunk' in this example) and make
    157 sure all other lines are commented::
     149A third option is to use a `path file`_ (``<something>.pth``). First, make sure
     150there are no files, directories or symlinks named ``django`` in your
     151``site-packages`` directory. Then create a text file named ``django.pth`` and
     152save it to your ``site-packages`` directory. That file should contain a path to
     153your copy of Django on a single line and optional comments. Here is an example
     154that points to multiple branches. Just uncomment the line for the branch you
     155want to use ('Trunk' in this example) and make sure all other lines are
     156commented::
    158157
    159158    # Trunk is a svn checkout of:
    160159    #   http://code.djangoproject.com/svn/django/trunk/
  • docs/internals/contributing/writing-code/submitting-patches.txt

     
    8484      Patches in ``git diff`` format are also acceptable.
    8585
    8686    * When creating patches, always run ``svn diff`` from the top-level
    87       ``trunk`` directory -- i.e., the one that contains ``django``, ``docs``,
     87      ``trunk`` directory -- i.e. the one that contains ``django``, ``docs``,
    8888      ``tests``, ``AUTHORS``, etc. This makes it easy for other people to
    8989      apply your patches.
    9090
     
    101101
    102102    * The code required to fix a problem or add a feature is an essential part
    103103      of a patch, but it is not the only part. A good patch should also
    104       include a regression test to validate the behavior that has been fixed
    105       (and prevent the problem from arising again).
     104      include a regression test to validate the behavior that has been fixed,
     105      to prevent the problem from arising again.
    106106
    107107    * If the code associated with a patch adds a new feature, or modifies
    108108      behavior of an existing feature, the patch should also contain
     
    130130best practice in this regard.
    131131
    132132To that end, patches for javascript files should include both the original
    133 code for future development (e.g. "foo.js"), and a compressed version for
    134 production use (e.g. "foo.min.js"). Any links to the file in the codebase
     133code for future development (e.g. ``foo.js``), and a compressed version for
     134production use (e.g. ``foo.min.js``). Any links to the file in the codebase
    135135should point to the compressed version.
    136136
    137137To simplify the process of providing optimized javascript code, Django
    138138includes a handy script which should be used to create a "minified" version.
    139 This script is located at ``/contrib/admin/media/js/compress.py``.
     139This script is located at ``django/contrib/admin/static/js/compress.py``.
    140140
    141141Behind the scenes, ``compress.py`` is a front-end for Google's
    142142`Closure Compiler`_ which is written in Java. However, the Closure Compiler
     
    148148higher on Mac OS X). Note that Mac OS X 10.5 and earlier did not ship with
    149149Java 1.6 by default, so it may be necessary to upgrade your Java installation
    150150before the tool will be functional. Also note that even after upgrading Java,
    151 the default `/usr/bin/java` command may remain linked to the previous Java
     151the default ``/usr/bin/java`` command may remain linked to the previous Java
    152152binary, so relinking that command may be necessary as well.
    153153
    154154Please don't forget to run ``compress.py`` and include the ``diff`` of the
  • docs/internals/contributing/writing-code/unit-tests.txt

     
    33==========
    44
    55Django comes with a test suite of its own, in the ``tests`` directory of the
    6 Django tarball. It's our policy to make sure all tests pass at all times.
     6code base. It's our policy to make sure all tests pass at all times.
    77
    88The tests cover:
    99
    10     * Models and the database API (``tests/modeltests/``).
    11     * Everything else in core Django code (``tests/regressiontests``)
    12     * Contrib apps (``django/contrib/<contribapp>/tests``, see below)
     10    * Models and the database API (``tests/modeltests``),
     11    * Everything else in core Django code (``tests/regressiontests``),
     12    * :ref:`contrib-apps` (``django/contrib/<app>/tests``).
    1313
    1414We appreciate any and all contributions to the test suite!
    1515
     
    105105    ./runtests.py --settings=path.to.settings generic_relations i18n
    106106
    107107How do you find out the names of individual tests? Look in
    108 ``tests/modeltests`` and ``tests/regressiontests`` -- each directory name
    109 there is the name of a test.
     108``tests/modeltests`` and ``tests/regressiontests`` each directory name
     109there is the name of a test. Contrib app names are also valid test names.
    110110
    111111If you just want to run a particular class of tests, you can specify a list of
    112112paths to individual test classes. For example, to run the ``TranslationTests``
     
    150150.. _memcached: http://www.danga.com/memcached/
    151151.. _gettext: http://www.gnu.org/software/gettext/manual/gettext.html
    152152
     153.. _contrib-apps:
     154
    153155Contrib apps
    154156------------
    155157
    156 Tests for apps in ``django/contrib/`` go in their respective directories under
    157 ``django/contrib/``, in a ``tests.py`` file. (You can split the tests over
    158 multiple modules by using a ``tests`` directory in the normal Python way.)
     158Tests for contrib apps go in their respective directories under
     159``django/contrib``, in a ``tests.py`` file. You can split the tests over
     160multiple modules by using a ``tests`` directory in the normal Python way.
    159161
    160 For the tests to be found, a ``models.py`` file must exist (it doesn't
    161 have to have anything in it). If you have URLs that need to be
    162 mapped, put them in ``tests/urls.py``.
     162For the tests to be found, a ``models.py`` file must exist, even if it's empty.
     163If you have URLs that need to be mapped, put them in ``tests/urls.py``.
    163164
    164165To run tests for just one contrib app (e.g. ``markup``), use the same
    165166method as above::
  • docs/internals/release-process.txt

     
    77Official releases
    88=================
    99
    10 Django's release numbering works as follows:
     10Since version 1.0, Django's release numbering works as follows:
    1111
    1212    * Versions are numbered in the form ``A.B`` or ``A.B.C``.
    1313
    1414    * ``A`` is the *major version* number, which is only incremented for major
    1515      changes to Django, and these changes are not necessarily
    16       backwards-compatible. That is, code you wrote for Django 6.0 may break
    17       when we release Django 7.0.
     16      backwards-compatible. That is, code you wrote for Django 1.2 may break
     17      when we release Django 2.0.
    1818
    1919    * ``B`` is the *minor version* number, which is incremented for large yet
    20       backwards compatible changes.  Code written for Django 6.4 will continue
    21       to work under Django 6.5.
     20      backwards compatible changes.  Code written for Django 1.2 will continue
     21      to work under Django 1.3. Exceptions to this rule will be listed in the
     22      release notes.
    2223
    23     * ``C`` is the *micro version* number which, is incremented for bug and
    24       security fixes.  A new micro-release will always be 100%
    25       backwards-compatible with the previous micro-release.
     24    * ``C`` is the *micro version* number, which is incremented for bug and
     25      security fixes. A new micro-release will be 100% backwards-compatible with
     26      the previous micro-release. The only exception is when a security issue
     27      can't be fixed without breaking backwards-compatibility. If this happens,
     28      the release notes will provide detailed upgrade instructions.
    2629
    2730    * In some cases, we'll make alpha, beta, or release candidate releases.
    2831      These are of the form ``A.B alpha/beta/rc N``, which means the ``Nth``
    2932      alpha/beta/release candidate of version ``A.B``.
    3033
    31 An exception to this version numbering scheme is the pre-1.0 Django code.
    32 There's no guarantee of backwards-compatibility until the 1.0 release.
    33 
    3434In Subversion, each Django release will be tagged under ``tags/releases``.  If
    3535it's necessary to release a bug fix release or a security release that doesn't
    3636come from the trunk, we'll copy that tag to ``branches/releases`` to make the
     
    7575Micro releases (1.0.1, 1.0.2, 1.1.1, etc.) will be issued at least once half-way
    7676between minor releases, and probably more often as needed.
    7777
    78 These releases will always be 100% compatible with the associated minor release
    79 -- the answer to "should I upgrade to the latest micro release?" will always be
    80 "yes."
     78These releases will be 100% compatible with the associated minor release, unless
     79this is impossible for security reasons. So the answer to "should I upgrade to
     80the latest micro release?" will always be "yes."
    8181
    8282Each minor release of Django will have a "release maintainer" appointed. This
    8383person will be responsible for making sure that bug fixes are applied to both
     
    9393    * The current development trunk will get new features and bug fixes
    9494      requiring major refactoring.
    9595
    96     * All bug fixes applied to the trunk will also be applied to the last
    97       minor release, to be released as the next micro release.
     96    * Patches applied to the trunk will also be applied to the last minor
     97      release, to be released as the next micro release, when they fix critical
     98      problems:
    9899
     100      * Security issues.
     101
     102      * Data-loss bugs.
     103
     104      * Crashing bugs.
     105
     106      * Major functionality bugs in newly-introduced features.
     107
     108      The rule of thumb is that fixes will be backported to the last minor
     109      release for bugs that would have prevented a release in the first place.
     110
    99111    * Security fixes will be applied to the current trunk and the previous two
    100112      minor releases.
    101113
     
    104116
    105117    * Features will be added to development trunk, to be released as Django 1.4.
    106118
    107     * Bug fixes will be applied to a ``1.3.X`` branch, and released as 1.3.1,
    108       1.3.2, etc.
     119    * Critical bug fixes will be applied to a ``1.3.X`` branch, and released as
     120      1.3.1, 1.3.2, etc.
    109121
    110     * Security releases will be applied to trunk, a ``1.3.X`` branch and a
    111       ``1.2.X`` branch. Security fixes will trigger the release of ``1.3.1``,
    112       ``1.2.1``, etc.
     122    * Security fixes will be applied to trunk, a ``1.3.X`` branch and a
     123      ``1.2.X`` branch. They will trigger the release of ``1.3.1``, ``1.2.1``,
     124      etc.
    113125
    114126.. _release-process:
    115127
     
    119131Django uses a time-based release schedule, with minor (i.e. 1.1, 1.2, etc.)
    120132releases every nine months, or more, depending on features.
    121133
    122 After each previous release (and after a suitable cooling-off period of a week
    123 or two), the core development team will examine the landscape and announce a
    124 timeline for the next release. Most releases will be scheduled in the 6-9 month
    125 range, but if we have bigger features to development we might schedule a longer
    126 period to allow for more ambitious work.
     134After each release, and after a suitable cooling-off period of a few weeks, the
     135core development team will examine the landscape and announce a timeline for the
     136next release. Most releases will be scheduled in the 6-9 month range, but if we
     137have bigger features to development we might schedule a longer period to allow
     138for more ambitious work.
    127139
    128140Release cycle
    129141-------------
     
    174186Bug-fix releases
    175187----------------
    176188
    177 After a minor release (i.e 1.1), the previous release will go into bug-fix mode.
     189After a minor release (e.g. 1.1), the previous release will go into bug-fix
     190mode.
    178191
    179192A branch will be created of the form ``branches/releases/1.0.X`` to track
    180 bug-fixes to the previous release. When possible, bugs fixed on trunk must
     193bug-fixes to the previous release. Critical bugs fixed on trunk must
    181194*also* be fixed on the bug-fix branch; this means that commits need to cleanly
    182195separate bug fixes from feature additions. The developer who commits a fix to
    183196trunk will be responsible for also applying the fix to the current bug-fix
     
    194207    * On trunk, development towards 1.2 proceeds with small additions, bugs
    195208      fixes, etc. being checked in daily.
    196209
    197     * On the branch "branches/releases/1.1.X", bug fixes found in the 1.1
    198       release are checked in as needed. At some point, this branch will be
    199       released as "1.1.1", "1.1.2", etc.
     210    * On the branch "branches/releases/1.1.X", fixes for critical bugs found in
     211      the 1.1 release are checked in as needed. At some point, this branch will
     212      be released as "1.1.1", "1.1.2", etc.
    200213
    201214    * On the branch "branches/releases/1.0.X", security fixes are made if
    202215      needed and released as "1.0.2", "1.0.3", etc.
  • docs/internals/deprecation.txt

     
    33===========================
    44
    55This document outlines when various pieces of Django will be removed, following
    6 their deprecation, as per the :ref:`Django deprecation policy
    7 <internal-release-deprecation-policy>`
     6their deprecation, as per the :ref:`deprecation policy
     7<internal-release-deprecation-policy>`.
    88
    9     * 1.3
    10         * ``AdminSite.root()``.  This release will remove the old method for
    11           hooking up admin URLs.  This has been deprecated since the 1.1
    12           release.
     91.3
     10---
    1311
    14         * Authentication backends need to define the boolean attributes
    15           ``supports_object_permissions`` and ``supports_anonymous_user``.
    16           The old backend style is deprecated since the 1.2 release.
     12    * ``AdminSite.root()``.  This release will remove the old method for
     13      hooking up admin URLs.  This has been deprecated since the 1.1
     14      release.
    1715
    18         * The :mod:`django.contrib.gis.db.backend` module, including the
    19           ``SpatialBackend`` interface, is deprecated since the 1.2 release.
     16    * Authentication backends need to define the boolean attributes
     17      ``supports_object_permissions`` and ``supports_anonymous_user``.
     18      The old backend style is deprecated since the 1.2 release.
    2019
    21     * 1.4
    22         * ``CsrfResponseMiddleware``.  This has been deprecated since the 1.2
    23           release, in favor of the template tag method for inserting the CSRF
    24           token.  ``CsrfMiddleware``, which combines ``CsrfResponseMiddleware``
    25           and ``CsrfViewMiddleware``, is also deprecated.
     20    * The :mod:`django.contrib.gis.db.backend` module, including the
     21      ``SpatialBackend`` interface, is deprecated since the 1.2 release.
    2622
    27         * The old imports for CSRF functionality (``django.contrib.csrf.*``),
    28           which moved to core in 1.2, will be removed.
     231.4
     24---
    2925
    30         * ``SMTPConnection``. The 1.2 release deprecated the ``SMTPConnection``
    31           class in favor of a generic E-mail backend API.
     26    * ``CsrfResponseMiddleware``.  This has been deprecated since the 1.2
     27      release, in favor of the template tag method for inserting the CSRF
     28      token.  ``CsrfMiddleware``, which combines ``CsrfResponseMiddleware``
     29      and ``CsrfViewMiddleware``, is also deprecated.
    3230
    33         * The many to many SQL generation functions on the database backends
    34           will be removed.
     31    * The old imports for CSRF functionality (``django.contrib.csrf.*``),
     32      which moved to core in 1.2, will be removed.
    3533
    36         * The ability to use the ``DATABASE_*`` family of top-level settings to
    37           define database connections will be removed.
     34    * ``SMTPConnection``. The 1.2 release deprecated the ``SMTPConnection``
     35      class in favor of a generic E-mail backend API.
    3836
    39         * The ability to use shorthand notation to specify a database backend
    40           (i.e., ``sqlite3`` instead of ``django.db.backends.sqlite3``) will be
    41           removed.
     37    * The many to many SQL generation functions on the database backends
     38      will be removed.
    4239
    43         * The ``get_db_prep_save``, ``get_db_prep_value`` and
    44           ``get_db_prep_lookup`` methods on Field were modified in 1.2
    45           to support multiple databases. In 1.4, the support functions
    46           that allow methods with the old prototype to continue
    47           working will be removed.
     40    * The ability to use the ``DATABASE_*`` family of top-level settings to
     41      define database connections will be removed.
    4842
    49         * The ``Message`` model (in ``django.contrib.auth``), its related
    50           manager in the ``User`` model (``user.message_set``), and the
    51           associated methods (``user.message_set.create()`` and
    52           ``user.get_and_delete_messages()``), which have
    53           been deprecated since the 1.2 release, will be removed.  The
    54           :doc:`messages framework </ref/contrib/messages>` should be used
    55           instead. The related ``messages`` variable returned by the
    56           auth context processor will also be removed. Note that this
    57           means that the admin application depends on the messages
    58           context processor.
     43    * The ability to use shorthand notation to specify a database backend
     44      (i.e., ``sqlite3`` instead of ``django.db.backends.sqlite3``) will be
     45      removed.
    5946
    60         * Authentication backends need to support the ``obj`` parameter for
    61           permission checking. The ``supports_object_permissions`` variable
    62           is not checked any longer and can be removed.
     47    * The ``get_db_prep_save``, ``get_db_prep_value`` and
     48      ``get_db_prep_lookup`` methods on Field were modified in 1.2
     49      to support multiple databases. In 1.4, the support functions
     50      that allow methods with the old prototype to continue
     51      working will be removed.
    6352
    64         * Authentication backends need to support the ``AnonymousUser``
    65           being passed to all methods dealing with permissions.
    66           The ``supports_anonymous_user`` variable is not checked any
    67           longer and can be removed.
     53    * The ``Message`` model (in ``django.contrib.auth``), its related
     54      manager in the ``User`` model (``user.message_set``), and the
     55      associated methods (``user.message_set.create()`` and
     56      ``user.get_and_delete_messages()``), which have
     57      been deprecated since the 1.2 release, will be removed.  The
     58      :doc:`messages framework </ref/contrib/messages>` should be used
     59      instead. The related ``messages`` variable returned by the
     60      auth context processor will also be removed. Note that this
     61      means that the admin application depends on the messages
     62      context processor.
    6863
    69         * The ability to specify a callable template loader rather than a
    70           ``Loader`` class will be removed, as will the ``load_template_source``
    71           functions that are included with the built in template loaders for
    72           backwards compatibility. These have been deprecated since the 1.2
    73           release.
     64    * Authentication backends need to support the ``obj`` parameter for
     65      permission checking. The ``supports_object_permissions`` variable
     66      is not checked any longer and can be removed.
    7467
    75         * ``django.utils.translation.get_date_formats()`` and
    76           ``django.utils.translation.get_partial_date_formats()``. These
    77           functions are replaced by the new locale aware formatting; use
    78           ``django.utils.formats.get_format()`` to get the appropriate
    79           formats.
     68    * Authentication backends need to support the ``AnonymousUser``
     69      being passed to all methods dealing with permissions.
     70      The ``supports_anonymous_user`` variable is not checked any
     71      longer and can be removed.
    8072
    81         * In ``django.forms.fields``: ``DEFAULT_DATE_INPUT_FORMATS``,
    82           ``DEFAULT_TIME_INPUT_FORMATS`` and
    83           ``DEFAULT_DATETIME_INPUT_FORMATS``. Use
    84           ``django.utils.formats.get_format()`` to get the appropriate
    85           formats.
     73    * The ability to specify a callable template loader rather than a
     74      ``Loader`` class will be removed, as will the ``load_template_source``
     75      functions that are included with the built in template loaders for
     76      backwards compatibility. These have been deprecated since the 1.2
     77      release.
    8678
    87         * The ability to use a function-based test runners will be removed,
    88           along with the ``django.test.simple.run_tests()`` test runner.
     79    * ``django.utils.translation.get_date_formats()`` and
     80      ``django.utils.translation.get_partial_date_formats()``. These
     81      functions are replaced by the new locale aware formatting; use
     82      ``django.utils.formats.get_format()`` to get the appropriate
     83      formats.
    8984
    90         * The ``views.feed()`` view and ``feeds.Feed`` class in
    91           ``django.contrib.syndication`` have been deprecated since the 1.2
    92           release. The class-based view ``views.Feed`` should be used instead.
     85    * In ``django.forms.fields``: ``DEFAULT_DATE_INPUT_FORMATS``,
     86      ``DEFAULT_TIME_INPUT_FORMATS`` and
     87      ``DEFAULT_DATETIME_INPUT_FORMATS``. Use
     88      ``django.utils.formats.get_format()`` to get the appropriate
     89      formats.
    9390
    94         * ``django.core.context_processors.auth``.  This release will
    95           remove the old method in favor of the new method in
    96           ``django.contrib.auth.context_processors.auth``.  This has been
    97           deprecated since the 1.2 release.
     91    * The ability to use a function-based test runners will be removed,
     92      along with the ``django.test.simple.run_tests()`` test runner.
    9893
    99         * The ``postgresql`` database backend has been deprecated in favor of
    100           the ``postgresql_psycopg2`` backend.
     94    * The ``views.feed()`` view and ``feeds.Feed`` class in
     95      ``django.contrib.syndication`` have been deprecated since the 1.2
     96      release. The class-based view ``views.Feed`` should be used instead.
    10197
    102         * The ``no`` language code has been deprecated in favor of the ``nb``
    103           language code.
     98    * ``django.core.context_processors.auth``.  This release will
     99      remove the old method in favor of the new method in
     100      ``django.contrib.auth.context_processors.auth``.  This has been
     101      deprecated since the 1.2 release.
    104102
    105         * Authentication backends need to define the boolean attribute
    106           ``supports_inactive_user``.
     103    * The ``postgresql`` database backend has been deprecated in favor of
     104      the ``postgresql_psycopg2`` backend.
    107105
    108         * ``django.db.models.fields.XMLField`` will be removed. This was
    109           deprecated as part of the 1.3 release. An accelerated deprecation
    110           schedule has been used because the field hasn't performed any role
    111           beyond that of a simple ``TextField`` since the removal of oldforms.
    112           All uses of ``XMLField`` can be replaced with ``TextField``.
     106    * The ``no`` language code has been deprecated in favor of the ``nb``
     107      language code.
    113108
    114     * 1.5
    115         * The ``mod_python`` request handler has been deprecated since the 1.3
    116           release. The ``mod_wsgi`` handler should be used instead.
     109    * Authentication backends need to define the boolean attribute
     110      ``supports_inactive_user``.
    117111
    118         * The ``template`` attribute on :class:`~django.test.client.Response`
    119           objects returned by the :ref:`test client <test-client>` has been
    120           deprecated since the 1.3 release. The
    121           :attr:`~django.test.client.Response.templates` attribute should be
    122           used instead.
     112    * ``django.db.models.fields.XMLField`` will be removed. This was
     113      deprecated as part of the 1.3 release. An accelerated deprecation
     114      schedule has been used because the field hasn't performed any role
     115      beyond that of a simple ``TextField`` since the removal of oldforms.
     116      All uses of ``XMLField`` can be replaced with ``TextField``.
    123117
    124         * The features of the :class:`django.test.simple.DjangoTestRunner`
    125           (including fail-fast and Ctrl-C test termination) can now be provided
    126           by the unittest-native :class:`TextTestRunner`. The
    127           :class:`~django.test.simple.DjangoTestRunner` will be removed in
    128           favor of using the unittest-native class.
     1181.5
     119---
    129120
    130         * The undocumented function
    131           :func:`django.contrib.formtools.utils.security_hash`
    132           is deprecated, in favor of :func:`django.contrib.formtools.utils.form_hmac`
     121    * The ``mod_python`` request handler has been deprecated since the 1.3
     122      release. The ``mod_wsgi`` handler should be used instead.
    133123
    134         * The function-based generic views have been deprecated in
    135           favor of their class-based cousins. The following modules
    136           will be removed:
     124    * The ``template`` attribute on :class:`~django.test.client.Response`
     125      objects returned by the :ref:`test client <test-client>` has been
     126      deprecated since the 1.3 release. The
     127      :attr:`~django.test.client.Response.templates` attribute should be
     128      used instead.
    137129
    138               * :mod:`django.views.generic.create_update`
    139               * :mod:`django.views.generic.date_based`
    140               * :mod:`django.views.generic.list_detail`
    141               * :mod:`django.views.generic.simple`
     130    * The features of the :class:`django.test.simple.DjangoTestRunner`
     131      (including fail-fast and Ctrl-C test termination) can now be provided
     132      by the unittest-native :class:`TextTestRunner`. The
     133      :class:`~django.test.simple.DjangoTestRunner` will be removed in
     134      favor of using the unittest-native class.
    142135
    143         * The :class:`~django.core.servers.basehttp.AdminMediaHandler` has
    144           been deprecated in favor of the
    145           :class:`~django.contrib.staticfiles.handlers.StaticFilesHandler`.
     136    * The undocumented function
     137      :func:`django.contrib.formtools.utils.security_hash`
     138      is deprecated, in favor of :func:`django.contrib.formtools.utils.form_hmac`
    146139
    147         * The :ttag:`url` and :ttag:`ssi` template tags will be
    148           modified so that the first argument to each tag is a
    149           template variable, not an implied string. The new-style
    150           behavior is provided in the ``future`` template tag library.
     140    * The function-based generic views have been deprecated in
     141      favor of their class-based cousins. The following modules
     142      will be removed:
    151143
    152         * The :djadmin:`reset` and :djadmin:`sqlreset` management commands
    153           are deprecated.
     144          * :mod:`django.views.generic.create_update`
     145          * :mod:`django.views.generic.date_based`
     146          * :mod:`django.views.generic.list_detail`
     147          * :mod:`django.views.generic.simple`
    154148
    155         * Authentication backends need to support a inactive user
    156           being passed to all methods dealing with permissions.
    157           The ``supports_inactive_user`` variable is not checked any
    158           longer and can be removed.
     149    * The :class:`~django.core.servers.basehttp.AdminMediaHandler` has
     150      been deprecated in favor of the
     151      :class:`~django.contrib.staticfiles.handlers.StaticFilesHandler`.
    159152
    160         * :meth:`~django.contrib.gis.geos.GEOSGeometry.transform` will raise
    161           a :class:`~django.contrib.gis.geos.GEOSException` when called
    162           on a geometry with no SRID value.
     153    * The :ttag:`url` and :ttag:`ssi` template tags will be
     154      modified so that the first argument to each tag is a
     155      template variable, not an implied string. The new-style
     156      behavior is provided in the ``future`` template tag library.
    163157
    164         * :class:`~django.http.CompatCookie` will be removed in favor of
    165           :class:`~django.http.SimpleCookie`.
     158    * The :djadmin:`reset` and :djadmin:`sqlreset` management commands
     159      are deprecated.
    166160
    167         * :class:`django.core.context_processors.PermWrapper` and
    168           :class:`django.core.context_processors.PermLookupDict`
    169           will be moved to :class:`django.contrib.auth.context_processors.PermWrapper`
    170           and :class:`django.contrib.auth.context_processors.PermLookupDict`,
    171           respectively.
     161    * Authentication backends need to support a inactive user
     162      being passed to all methods dealing with permissions.
     163      The ``supports_inactive_user`` variable is not checked any
     164      longer and can be removed.
    172165
    173         * The :setting:`MEDIA_URL` or :setting:`STATIC_URL` settings are
    174           required to end with a trailing slash to ensure there is a consistent
    175           way to combine paths in templates.
     166    * :meth:`~django.contrib.gis.geos.GEOSGeometry.transform` will raise
     167      a :class:`~django.contrib.gis.geos.GEOSException` when called
     168      on a geometry with no SRID value.
    176169
    177     * 1.6
    178         * The compatibility modules ``django.utils.copycompat`` and
    179           ``django.utils.hashcompat`` as well as the functions
    180           ``django.utils.itercompat.all`` and ``django.utils.itercompat.any``
    181           have been deprecated since the 1.4 release. The native versions
    182           should be used instead.
     170    * :class:`~django.http.CompatCookie` will be removed in favor of
     171      :class:`~django.http.SimpleCookie`.
    183172
    184         * The :func:`~django.views.decorators.csrf.csrf_response_exempt` and
    185           :func:`~django.views.decorators.csrf.csrf_view_exempt` decorators will
    186           be removed. Since 1.4 ``csrf_response_exempt`` has been a no-op (it
    187           returns the same function), and ``csrf_view_exempt`` has been a
    188           synonym for ``django.views.decorators.csrf.csrf_exempt``, which should
    189           be used to replace it.
     173    * :class:`django.core.context_processors.PermWrapper` and
     174      :class:`django.core.context_processors.PermLookupDict`
     175      will be moved to :class:`django.contrib.auth.context_processors.PermWrapper`
     176      and :class:`django.contrib.auth.context_processors.PermLookupDict`,
     177      respectively.
    190178
    191         * The :class:`~django.core.cache.backends.memcached.CacheClass` backend
    192           was split into two in Django 1.3 in order to introduce support for
    193           PyLibMC. The historical :class:`~django.core.cache.backends.memcached.CacheClass`
    194           is now an alias for :class:`~django.core.cache.backends.memcached.MemcachedCache`.
    195           In Django 1.6, the historical alias will be removed.
     179    * The :setting:`MEDIA_URL` or :setting:`STATIC_URL` settings are
     180      required to end with a trailing slash to ensure there is a consistent
     181      way to combine paths in templates.
    196182
    197         * The UK-prefixed objects of ``django.contrib.localflavor.uk`` will only
    198           be accessible through their new GB-prefixed names (GB is the correct
    199           ISO 3166 code for United Kingdom). They have been deprecated since the
    200           1.4 release.
     1831.6
     184---
    201185
    202         * The :setting:`IGNORABLE_404_STARTS` and :setting:`IGNORABLE_404_ENDS`
    203           settings have been superseded by :setting:`IGNORABLE_404_URLS` in
    204           the 1.4 release. They will be removed.
     186    * The compatibility modules ``django.utils.copycompat`` and
     187      ``django.utils.hashcompat`` as well as the functions
     188      ``django.utils.itercompat.all`` and ``django.utils.itercompat.any``
     189      have been deprecated since the 1.4 release. The native versions
     190      should be used instead.
    205191
    206         * The :doc:`form wizard </ref/contrib/formtools/form-wizard>` has been
    207           refactored to use class based views with pluggable backends in 1.4.
    208           The previous implementation will be deprecated.
     192    * The :func:`~django.views.decorators.csrf.csrf_response_exempt` and
     193      :func:`~django.views.decorators.csrf.csrf_view_exempt` decorators will
     194      be removed. Since 1.4 ``csrf_response_exempt`` has been a no-op (it
     195      returns the same function), and ``csrf_view_exempt`` has been a
     196      synonym for ``django.views.decorators.csrf.csrf_exempt``, which should
     197      be used to replace it.
    209198
    210         * Legacy ways of calling
    211           :func:`~django.views.decorators.cache.cache_page` will be removed.
     199    * The :class:`~django.core.cache.backends.memcached.CacheClass` backend
     200      was split into two in Django 1.3 in order to introduce support for
     201      PyLibMC. The historical :class:`~django.core.cache.backends.memcached.CacheClass`
     202      is now an alias for :class:`~django.core.cache.backends.memcached.MemcachedCache`.
     203      In Django 1.6, the historical alias will be removed.
    212204
    213         * The backward-compatibility shim to automatically add a debug-false
    214           filter to the ``'mail_admins'`` logging handler will be removed. The
    215           :setting:`LOGGING` setting should include this filter explicitly if
    216           it is desired.
     205    * The UK-prefixed objects of ``django.contrib.localflavor.uk`` will only
     206      be accessible through their new GB-prefixed names (GB is the correct
     207      ISO 3166 code for United Kingdom). They have been deprecated since the
     208      1.4 release.
    217209
    218         * The template tag
    219           :func:`django.contrib.admin.templatetags.adminmedia.admin_media_prefix`
    220           was deprecated since Django 1.4 and will be removed in favor of the
    221           generic static files handling.
     210    * The :setting:`IGNORABLE_404_STARTS` and :setting:`IGNORABLE_404_ENDS`
     211      settings have been superseded by :setting:`IGNORABLE_404_URLS` in
     212      the 1.4 release. They will be removed.
    222213
    223         * The builin truncation functions
    224           :func:`django.utils.text.truncate_words` and
    225           :func:`django.utils.text.truncate_html_words`
    226           were deprecated since Django 1.4 and will be removed in favor
    227           of the ``django.utils.text.Truncator`` class.
     214    * The :doc:`form wizard </ref/contrib/formtools/form-wizard>` has been
     215      refactored to use class based views with pluggable backends in 1.4.
     216      The previous implementation will be deprecated.
    228217
    229     * 2.0
    230         * ``django.views.defaults.shortcut()``. This function has been moved
    231           to ``django.contrib.contenttypes.views.shortcut()`` as part of the
    232           goal of removing all ``django.contrib`` references from the core
    233           Django codebase. The old shortcut will be removed in the 2.0
    234           release.
     218    * Legacy ways of calling
     219      :func:`~django.views.decorators.cache.cache_page` will be removed.
     220
     221    * The backward-compatibility shim to automatically add a debug-false
     222      filter to the ``'mail_admins'`` logging handler will be removed. The
     223      :setting:`LOGGING` setting should include this filter explicitly if
     224      it is desired.
     225
     226    * The template tag
     227      :func:`django.contrib.admin.templatetags.adminmedia.admin_media_prefix`
     228      was deprecated since Django 1.4 and will be removed in favor of the
     229      generic static files handling.
     230
     231    * The builin truncation functions
     232      :func:`django.utils.text.truncate_words` and
     233      :func:`django.utils.text.truncate_html_words`
     234      were deprecated since Django 1.4 and will be removed in favor
     235      of the ``django.utils.text.Truncator`` class.
     236
     2372.0
     238---
     239
     240    * ``django.views.defaults.shortcut()``. This function has been moved
     241      to ``django.contrib.contenttypes.views.shortcut()`` as part of the
     242      goal of removing all ``django.contrib`` references from the core
     243      Django codebase. The old shortcut will be removed in the 2.0
     244      release.
Back to Top