mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-06-05 11:39:13 +00:00
Code Issues 32 Releases Wiki Activity

Fixed #16469 -- Improved documentation of Django internals, including the new backport policy. Many thanks to Aymeric Augustin.

Browse Source 
git-svn-id: http://code.djangoproject.com/svn/django/trunk@16548 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Jannis Leidel 2011-07-19 13:16:09 +00:00
parent 8f7b5024b2
commit 127b7fdce8
13 changed files with 441 additions and 369 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

63
docs/internals/contributing/bugs-and-features.txt
View File

@ -2,14 +2,14 @@
Reporting bugs and requesting features Reporting bugs and requesting features
====================================== ======================================
Before reporting a bug or requesting a new feature please consider these Before reporting a bug or requesting a new feature, please consider these
general points: general points:
* Check that someone hasn't already filed the bug or feature request by * Check that someone hasn't already filed the bug or feature request by
`searching`_ or running `custom queries`_ in the ticket tracker. `searching`_ or running `custom queries`_ in the ticket tracker.
* Don't use the ticket system to ask support questions. Use the * Don't use the ticket system to ask support questions. Use the
`django-users`_ list, or the `#django`_ IRC channel for that. `django-users`_ list or the `#django`_ IRC channel for that.
* Don't reopen issues that have been marked "wontfix" by a core developer. * Don't reopen issues that have been marked "wontfix" by a core developer.
This mark means that the decision has been made that we can't or won't fix This mark means that the decision has been made that we can't or won't fix
@ -17,7 +17,7 @@ general points:
on `django-developers`_. on `django-developers`_.
* Don't use the ticket tracker for lengthy discussions, because they're * Don't use the ticket tracker for lengthy discussions, because they're
likely to get lost. If a particular ticket is controversial, please move likely to get lost. If a particular ticket is controversial, please move the
discussion to `django-developers`_. discussion to `django-developers`_.
.. _reporting-bugs: .. _reporting-bugs:
@ -33,19 +33,19 @@ particular:
* **Do** read the :doc:`FAQ </faq/index>` to see if your issue might * **Do** read the :doc:`FAQ </faq/index>` to see if your issue might
be a well-known question. be a well-known question.
* **Do** ask on `django-users`_ *first* if you're not sure if what you're * **Do** ask on `django-users`_ or `#django`_ *first* if you're not sure if
seeing is a bug. what you're seeing is a bug.
* **Do** write complete, reproducible, specific bug reports. Include as * **Do** write complete, reproducible, specific bug reports. You must
much information as you possibly can, complete with code snippets, test include a clear, concise description of the problem, and a set of
cases, etc. This means including a clear, concise description of the instructions for replicating it. Add as much debug information as you can:
problem, and a clear set of instructions for replicating the problem. code snippets, test cases, exception backtraces, screenshots, etc. A nice
A minimal example that illustrates the bug in a nice small test case small test case is the best way to report a bug, as it gives us an easy
is the best possible bug report. way to confirm the bug quickly.
* **Don't** post to django-developers just to announce that you have filed * **Don't** post to `django-developers`_ just to announce that you have
a bug report. All the tickets are mailed to another list filed a bug report. All the tickets are mailed to another list,
(`django-updates`_), which is tracked by developers and interested `django-updates`_, which is tracked by developers and interested
community members; we see them as they are filed. community members; we see them as they are filed.
To understand the lifecycle of your ticket once you have created it, refer to To understand the lifecycle of your ticket once you have created it, refer to
@ -95,8 +95,18 @@ Requesting features
We're always trying to make Django better, and your feature requests are a key We're always trying to make Django better, and your feature requests are a key
part of that. Here are some tips on how to make a request most effectively: part of that. Here are some tips on how to make a request most effectively:
* First request the feature on `django-developers`_, not in the ticket * Make sure the feature actually requires changes in Django's core. If your
tracker. It'll get read more closely if it's on the mailing list. idea can be developed as an independent application or module — for
instance, you want to support another database engine — we'll probably
suggest that you to develop it independently. Then, if your project
gathers sufficient community support, we may consider it for inclusion in
Django.
* First request the feature on the `django-developers`_ list, not in the
ticket tracker. It'll get read more closely if it's on the mailing list.
This is even more important for large-scale feature requests. We like to
discuss any big changes to Django's core on the mailing list before
actually working on them.
* Describe clearly and concisely what the missing feature is and how you'd * Describe clearly and concisely what the missing feature is and how you'd
like to see it implemented. Include example code (non-functional is OK) like to see it implemented. Include example code (non-functional is OK)
@ -107,19 +117,16 @@ part of that. Here are some tips on how to make a request most effectively:
you'll need to explain it, if it isn't obvious why the feature would be you'll need to explain it, if it isn't obvious why the feature would be
useful. useful.
* Don't use the ticket system to make large-scale feature requests. If core developers agree on the feature, then it's appropriate to create a
We like to discuss any big changes to Django's core on the ticket. Include a link the discussion on `django-developers`_ in the ticket
`django-developers`_ list before actually working on them. description.
As with most open-source projects, code talks. If you are willing to write the As with most open-source projects, code talks. If you are willing to write the
code for the feature yourself or if (even better) you've already written it, code for the feature yourself or, even better, if you've already written it,
it's much more likely to be accepted. If it's a large feature that might need it's much more likely to be accepted. If it's a large feature that might need
multiple developers, we're always happy to give you an experimental branch in multiple developers, we're always happy to give you an experimental branch in
our repository; see the :doc:`writing-code/branch-policy`. our repository; see the :doc:`writing-code/branch-policy`.
To understand the lifecycle of your ticket once you have created it, refer to
:doc:`triaging-tickets`.
See also: :ref:`documenting-new-features`. See also: :ref:`documenting-new-features`.
.. _how-we-make-decisions: .. _how-we-make-decisions:
@ -141,9 +148,9 @@ votes are given as +1, +0, -0, or -1. Roughly translated, these votes mean:
* -1: "I strongly disagree and would be very unhappy to see the idea turn * -1: "I strongly disagree and would be very unhappy to see the idea turn
into reality." into reality."
Although these votes on django-developers are informal, they'll be taken very Although these votes on `django-developers`_ are informal, they'll be taken very
seriously. After a suitable voting period, if an obvious consensus arises seriously. After a suitable voting period, if an obvious consensus arises we'll
we'll follow the votes. follow the votes.
However, consensus is not always possible. If consensus cannot be reached, or However, consensus is not always possible. If consensus cannot be reached, or
if the discussion towards a consensus fizzles out without a concrete decision, if the discussion towards a consensus fizzles out without a concrete decision,
@ -175,7 +182,7 @@ committers -- may be held in private.
.. _searching: http://code.djangoproject.com/search .. _searching: http://code.djangoproject.com/search
.. _`custom queries`: https://code.djangoproject.com/query .. _custom queries: https://code.djangoproject.com/query
.. _django-developers: http://groups.google.com/group/django-developers .. _django-developers: http://groups.google.com/group/django-developers
.. _django-users: http://groups.google.com/group/django-users .. _django-users: http://groups.google.com/group/django-users
.. _`#django`: irc://irc.freenode.net/django .. _#django: irc://irc.freenode.net/django

20
docs/internals/contributing/committing-code.txt
View File

@ -28,11 +28,9 @@ Partial committers
in question is likely to be sufficient. in question is likely to be sufficient.
Decisions on new committers will follow the process explained in Decisions on new committers will follow the process explained in
:ref:`how-we-make-decisions`. :ref:`how-we-make-decisions`. To request commit access, please contact an
existing committer privately. Public requests for commit access are potential
To request commit access, please contact an existing committer privately. flame-war starters, and will be ignored.
Public requests for commit access are potential flame-war starters, and
will be ignored.
Committing guidelines Committing guidelines
--------------------- ---------------------
@ -69,12 +67,12 @@ repository:
* Separate bug fixes from feature changes. * Separate bug fixes from feature changes.
Bug fixes need to be added to the current bugfix branch (e.g. the Bug fixes need to be added to the current bugfix branch as well as the
``1.0.X`` branch) as well as the current trunk. current trunk.
* If your commit closes a ticket in the Django `ticket tracker`_, begin * If your commit closes a ticket in the Django `ticket tracker`_, begin
your commit message with the text "Fixed #abc", where "abc" is the your commit message with the text "Fixed #abc", where "abc" is the
number of the ticket your commit fixes. Example: "Fixed #123 -- Adde number of the ticket your commit fixes. Example: "Fixed #123 -- Added
support for foo". We've rigged Subversion and Trac so that any commit support for foo". We've rigged Subversion and Trac so that any commit
message in that format will automatically close the referenced ticket message in that format will automatically close the referenced ticket
and post a comment to it with the full commit message. and post a comment to it with the full commit message.
@ -83,7 +81,7 @@ repository:
first, then the "Fixed #abc." For example: first, then the "Fixed #abc." For example:
"magic-removal: Fixed #123 -- Added whizbang feature." "magic-removal: Fixed #123 -- Added whizbang feature."
For the curious: We're using a `Trac post-commit hook`_ for this. For the curious: we're using a `Trac post-commit hook`_ for this.
.. _Trac post-commit hook: http://trac.edgewall.org/browser/trunk/contrib/trac-post-commit-hook .. _Trac post-commit hook: http://trac.edgewall.org/browser/trunk/contrib/trac-post-commit-hook
@ -111,8 +109,8 @@ discovered, please follow these guidelines:
* If the original author can't be reached (within a reasonable amount * If the original author can't be reached (within a reasonable amount
of time -- a day or so) and the problem is severe -- crashing bug, of time -- a day or so) and the problem is severe -- crashing bug,
major test failures, etc -- then ask for objections on django-dev major test failures, etc -- then ask for objections on the
then revert if there are none. `django-developers`_ mailing list then revert if there are none.
* If the problem is small (a feature commit after feature freeze, * If the problem is small (a feature commit after feature freeze,
say), wait it out. say), wait it out.

53
docs/internals/contributing/index.txt
View File

@ -2,33 +2,51 @@
Contributing to Django Contributing to Django
====================== ======================
Django is a community that lives on its volunteers. As it keeps growing, we
always need more people to help others. As soon as you learn Django, you can
contribute in many ways:
* Join the `django-users`_ mailing list and answer questions. This
mailing list has a huge audience, and we really want to maintain a
friendly and helpful atmosphere. If you're new to the Django community,
you should read the `posting guidelines`_.
* Join the `#django IRC channel`_ on Freenode and answer questions. By
explaining Django to other users, you're going to learn a lot about the
framework yourself.
* Blog about Django. We syndicate all the Django blogs we know about on
the `community page`_; if you'd like to see your blog on that page you
can `register it here`_.
* Contribute to open-source Django projects, write some documentation, or
release your own code as an open-source pluggable application. The
ecosystem of pluggable applications is a big strength of Django, help us
build it!
If you think working *with* Django is fun, wait until you start working *on* If you think working *with* Django is fun, wait until you start working *on*
it. We're passionate about helping Django users make the jump to contributing it. We're passionate about helping Django users make the jump to contributing
members of the community, so there are several ways you can help Django's members of the community, so there are several ways you can help Django's
development: development:
* Blog about Django. We syndicate all the Django blogs we know about on * :doc:`Report bugs <bugs-and-features>` in our `ticket tracker`_.
the `community page`_; if you'd like to see your blog on that page you
can `register it here`_.
* :doc:`Report bugs and request features<bugs-and-features>` in our
`ticket tracker`_.
* Join the `django-developers`_ mailing list and share your ideas for how * Join the `django-developers`_ mailing list and share your ideas for how
to improve Django. We're always open to suggestions. to improve Django. We're always open to suggestions.
* :doc:`Submit patches<writing-code/submitting-patches>` for new and/or * :doc:`Submit patches <writing-code/submitting-patches>` for new and/or
fixed behavior. If you're looking for an easy way to start contributing fixed behavior. If you're looking for an easy way to start contributing
to Django have a look at the `easy pickings`_ tickets. to Django have a look at the `easy pickings`_ tickets.
* :doc:`Improve the documentation<writing-documentation>` or * :doc:`Improve the documentation <writing-documentation>` or
:doc:`write unit tests<writing-code/unit-tests>`. :doc:`write unit tests <writing-code/unit-tests>`.
* :doc:`Triage tickets<triaging-tickets>` that have been created by other * :doc:`Triage tickets and review patches <triaging-tickets>` created by
users. other users.
... and many more ways! Really, **ANYONE** can do something to help make Really, **ANYONE** can do something to help make Django better and greater!
Django better and greater. Browse the following sections to find out how:
Browse the following sections to find out how:
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
@ -41,8 +59,11 @@ Django better and greater. Browse the following sections to find out how:
translations translations
committing-code committing-code
.. _django-users: http://groups.google.com/group/django-users
.. _posting guidelines: https://code.djangoproject.com/wiki/UsingTheMailingList
.. _#django IRC channel: irc://irc.freenode.net/django
.. _community page: http://www.djangoproject.com/community/
.. _register it here: http://www.djangoproject.com/community/add/blogs/
.. _django-developers: http://groups.google.com/group/django-developers .. _django-developers: http://groups.google.com/group/django-developers
.. _ticket tracker: http://code.djangoproject.com/newticket .. _ticket tracker: http://code.djangoproject.com/newticket
.. _community page: http://www.djangoproject.com/community/ .. _easy pickings: http://code.djangoproject.com/query?status=!closed&easy=1
.. _`easy pickings`: http://code.djangoproject.com/query?status=!closed&easy=1
.. _`register it here`: http://www.djangoproject.com/community/add/blogs/

48
docs/internals/contributing/new-contributors.txt
View File

@ -5,15 +5,14 @@ Advice for new contributors
New contributor and not sure what to do? Want to help but just don't know how New contributor and not sure what to do? Want to help but just don't know how
to get started? This is the section for you. to get started? This is the section for you.
* **Pick a subject area that you care about, that you are familiar with, or First steps
that you want to learn about** -----------
You don't already have to be an expert on the area you want to work on; you Start with these easy tasks to discover Django's development process.
become an expert through your ongoing contributions to the code.
* **Triage tickets** * **Triage tickets**
If a ticket is unreviewed and reports a bug, try and reproduce it. If you If an `unreviewed ticket`_ reports a bug, try and reproduce it. If you
can reproduce it and it seems valid, make a note that you confirmed the bug can reproduce it and it seems valid, make a note that you confirmed the bug
and accept the ticket. Make sure the ticket is filed under the correct and accept the ticket. Make sure the ticket is filed under the correct
component area. Consider writing a patch that adds a test for the bug's component area. Consider writing a patch that adds a test for the bug's
@ -44,7 +43,30 @@ to get started? This is the section for you.
:doc:`writing-documentation`, in particular the tips for :doc:`writing-documentation`, in particular the tips for
:ref:`improving-the-documentation`. :ref:`improving-the-documentation`.
* **Analyze the ticket's context and history** .. note::
The `reports page`_ contains links to many useful Trac queries, including
several that are useful for triaging tickets and reviewing patches as
suggested above.
.. _reports page: http://code.djangoproject.com/wiki/Reports
.. _unreviewed ticket: http://code.djangoproject.com/query?status=!closed&stage=Unreviewed
Guidelines
----------
As a newcomer on a large project, it's easy to experience frustration. Here's
some advice to make your work on Django more useful and rewarding.
* **Pick a subject area that you care about, that you are familiar with, or
that you want to learn about**
You don't already have to be an expert on the area you want to work on; you
become an expert through your ongoing contributions to the code.
* **Analyze tickets' context and history**
Trac isn't an absolute; the context is just as important as the words. Trac isn't an absolute; the context is just as important as the words.
When reading Trac, you need to take into account who says things, and when When reading Trac, you need to take into account who says things, and when
@ -96,13 +118,7 @@ to get started? This is the section for you.
writing the very first tests for that feature, not that you get a pass from writing the very first tests for that feature, not that you get a pass from
writing tests altogether. writing tests altogether.
.. note:: .. _easy pickings: http://code.djangoproject.com/query?status=!closed&easy=1
The `Reports page`_ contains links to many useful Trac queries, including
several that are useful for triaging tickets and reviewing patches as
suggested above.
.. _Reports page: http://code.djangoproject.com/wiki/Reports
.. _new-contributors-faq: .. _new-contributors-faq:
@ -114,7 +130,7 @@ FAQ
First off, it's not personal. Django is entirely developed by volunteers First off, it's not personal. Django is entirely developed by volunteers
(even the core developers), and sometimes folks just don't have time. The (even the core developers), and sometimes folks just don't have time. The
best thing to do is to send a gentle reminder to the Django Developers best thing to do is to send a gentle reminder to the django-developers
mailing list asking for review on the ticket, or to bring it up in the mailing list asking for review on the ticket, or to bring it up in the
#django-dev IRC channel. #django-dev IRC channel.
@ -130,8 +146,6 @@ FAQ
Design Decision Needed requires consensus about the right solution. At the Design Decision Needed requires consensus about the right solution. At the
very least it needs consensus among the core developers, and ideally it has very least it needs consensus among the core developers, and ideally it has
consensus from the community as well. The best way to accomplish this is to consensus from the community as well. The best way to accomplish this is to
start a thread on the Django Developers mailing list, and for very complex start a thread on the django-developers mailing list, and for very complex
issues to start a wiki page summarizing the problem and the possible issues to start a wiki page summarizing the problem and the possible
solutions. solutions.
.. _`easy pickings`: http://code.djangoproject.com/query?status=!closed&easy=1

54
docs/internals/contributing/translations.txt
View File

@ -3,16 +3,21 @@ Submitting and maintaining translations
======================================= =======================================
Various parts of Django, such as the admin site and validation error messages, Various parts of Django, such as the admin site and validation error messages,
are internationalized. This means they display different text depending on a are internationalized. This means they display different text depending on each
user's language setting. For this, Django uses the same internationalization user's language setting. For this, Django uses the same internationalization and
infrastructure available to Django applications described in the localization infrastructure available to Django applications, described in the
:doc:`i18n documentation</topics/i18n/index>`. :doc:`i18n documentation</topics/i18n/index>`.
These translations are contributed by Django users worldwide. If you find an Internationalization
incorrect translation or want to discuss specific translations, go to the --------------------
`translation team`_ page for that language. If you would like to help out
with translating or add a language that isn't yet translated, here's what Translations are contributed by Django users worldwide. The translation work is
to do: coordinated at `Transifex`_.
If you find an incorrect translation or want to discuss specific translations,
go to the `translation team`_ page for that language. If you would like to help
out with translating or add a language that isn't yet translated, here's what to
do:
* Join the `Django i18n mailing list`_ and introduce yourself. * Join the `Django i18n mailing list`_ and introduce yourself.
@ -20,7 +25,7 @@ to do:
* Signup at `Transifex`_ and visit the `Django project page`_. * Signup at `Transifex`_ and visit the `Django project page`_.
* On the "`Translation Teams`_" page, choose the language team you want * On the `translation teams`_ page, choose the language team you want
to work with, **or** -- in case the language team doesn't exist yet -- to work with, **or** -- in case the language team doesn't exist yet --
request a new team by clicking on the "Request a new team" button request a new team by clicking on the "Request a new team" button
and select the appropriate language. and select the appropriate language.
@ -37,24 +42,27 @@ to do:
Each of the contrib apps also have a resource (prefixed with "contrib"). Each of the contrib apps also have a resource (prefixed with "contrib").
.. note:: .. note::
For more information about how to use Transifex, see the For more information about how to use Transifex, read the
`Transifex Help`_ `Transifex User Guide`_.
* Optionally, review and update the ``conf/locale/<locale>/formats.py`` Localization
file to describe the date, time and numbers formatting particularities ------------
of your locale. These files aren't covered by the use of Transifex and
require a patch against the Django source tree, just as a code change
would:
* Create a diff against the current Subversion trunk. You can also review ``conf/locale/<locale>/formats.py``. This file describes
the date, time and numbers formatting particularities of your locale. See
:ref:`format-localization` for details.
* Open a ticket in Django's ticket system, set its ``Component`` field The format files aren't managed by the use of Transifex. To change them, you
to ``Translations``, and attach the patch to it. See must :doc:`create a patch<writing-code/submitting-patches>` against the Django source tree, as for any code change:
:ref:`format-localization` for details.
* Create a diff against the current Subversion trunk.
* Open a ticket in Django's ticket system, set its ``Component`` field to
``Translations``, and attach the patch to it.
.. _Django i18n mailing list: http://groups.google.com/group/django-i18n/
.. _Transifex: http://www.transifex.net/ .. _Transifex: http://www.transifex.net/
.. _Django i18n mailing list: http://groups.google.com/group/django-i18n/
.. _Django project page: http://www.transifex.net/projects/p/django/ .. _Django project page: http://www.transifex.net/projects/p/django/
.. _translation teams: http://www.transifex.net/projects/p/django/teams/
.. _translation team: http://www.transifex.net/projects/p/django/teams/ .. _translation team: http://www.transifex.net/projects/p/django/teams/
.. _Transifex Help: http://help.transifex.net/ .. _translation teams: http://www.transifex.net/projects/p/django/teams/
.. _Transifex User Guide: http://help.transifex.net/

40
docs/internals/contributing/triaging-tickets.txt
View File

@ -2,16 +2,17 @@
Triaging tickets Triaging tickets
================ ================
Django uses Trac_ for managing our progress, and Trac is a community-tended Django uses Trac_ for managing the work on the code base. Trac is a
garden of the bugs people have found and the features people would like to see community-tended garden of the bugs people have found and the features people
added. As in any garden, sometimes there are weeds to be pulled and sometimes would like to see added. As in any garden, sometimes there are weeds to be
there are flowers and vegetables that need picking. We need your help to sort pulled and sometimes there are flowers and vegetables that need picking. We need
out one from the other, and in the end we all benefit together. your help to sort out one from the other, and in the end we all benefit
together.
Like all gardens, we can aspire to perfection but in reality there's no such Like all gardens, we can aspire to perfection but in reality there's no such
thing. Even in the most pristine garden there are still snails and insects. thing. Even in the most pristine garden there are still snails and insects.
In a community garden there are also helpful people who--with the best of In a community garden there are also helpful people who -- with the best of
intentions--fertilize the weeds and poison the roses. It's the job of the intentions -- fertilize the weeds and poison the roses. It's the job of the
community as a whole to self-manage, keep the problems to a minimum, and community as a whole to self-manage, keep the problems to a minimum, and
educate those coming into the community so that they can become valuable educate those coming into the community so that they can become valuable
contributing members. contributing members.
@ -39,8 +40,8 @@ tickets have patches, but those patches don't meet all the requirements of a
:ref:`good patch<patch-style>`. :ref:`good patch<patch-style>`.
One way to help out is to *triage* tickets that have been created by other One way to help out is to *triage* tickets that have been created by other
users. The core team--as well as many community members--work on this users. The core team and several community members work on this regularly, but
regularly, but more help is always appreciated. more help is always appreciated.
Most of the workflow is based around the concept of a ticket's Most of the workflow is based around the concept of a ticket's
:ref:`triage stages <triage-stages>`. Each stage describes where in its :ref:`triage stages <triage-stages>`. Each stage describes where in its
@ -146,11 +147,10 @@ made by the core committers, however that is not a requirement. See the
:ref:`New contributors' FAQ<new-contributors-faq>` for "My ticket has been in :ref:`New contributors' FAQ<new-contributors-faq>` for "My ticket has been in
DDN forever! What should I do?" DDN forever! What should I do?"
This stage will generally only be used for feature This stage will often be used for feature requests. It can also be used for
requests. It can also be used for issues that *might* be bugs, depending on issues that *might* be bugs, depending on opinion or interpretation. Obvious
opinion or interpretation. Obvious bugs (such as crashes, incorrect query bugs (such as crashes, incorrect query results, or non-compliance with a
results, or non-compliance with a standard) skip this stage and move straight standard) skip this stage and move straight to "Accepted".
to "Accepted".
Ready For Checkin Ready For Checkin
~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
@ -200,7 +200,7 @@ A number of flags, appearing as checkboxes in Trac, can be set on a ticket:
This flag means that although the ticket *has* a patch, it's not quite This flag means that although the ticket *has* a patch, it's not quite
ready for checkin. This could mean the patch no longer applies ready for checkin. This could mean the patch no longer applies
cleanly, there is a flaw in the implementation, or that the code cleanly, there is a flaw in the implementation, or that the code
doesn't meet our standards." doesn't meet our standards.
* Easy pickings * Easy pickings
Tickets that would require small, easy, patches. Tickets that would require small, easy, patches.
@ -250,7 +250,7 @@ If you do close a ticket, you should always make sure of the following:
* If there is a way they can improve the ticket to reopen it, let them know. * If there is a way they can improve the ticket to reopen it, let them know.
* If the ticket is a duplicate, reference the original ticket. Also * If the ticket is a duplicate, reference the original ticket. Also
cross-reference the closed ticket by living a comment in the original one cross-reference the closed ticket by leaving a comment in the original one
-- this allows to access more related information about the reported bug -- this allows to access more related information about the reported bug
or requested feature. or requested feature.
@ -279,7 +279,7 @@ A ticket can be resolved in a number of ways:
discussion in the `django-developers`_ mailing list. Feel free to discussion in the `django-developers`_ mailing list. Feel free to
start or join in discussions of "wontfix" tickets on the start or join in discussions of "wontfix" tickets on the
django-developers_ mailing list, but please do not reopen tickets django-developers_ mailing list, but please do not reopen tickets
closed as "wontfix" by core developers. closed as "wontfix" by a :doc:`core developer</internals/committers>`.
* duplicate * duplicate
Used when another ticket covers the same issue. By closing duplicate Used when another ticket covers the same issue. By closing duplicate
@ -371,9 +371,9 @@ the ticket database:
checkin", but you should get at minimum one other community member to checkin", but you should get at minimum one other community member to
review a patch that you submit. review a patch that you submit.
* Please **don't** reverse a decision that has been made by a core * Please **don't** reverse a decision that has been made by a :doc:`core
developer. If you disagree with a decision that has been made, developer</internals/committers>`. If you disagree with a decision that
please post a message to `django-developers`_. has been made, please post a message to `django-developers`_.
* If you're unsure if you should be making a change, don't make the * If you're unsure if you should be making a change, don't make the
change but instead leave a comment with your concerns on the ticket, change but instead leave a comment with your concerns on the ticket,

17
docs/internals/contributing/writing-code/branch-policy.txt
View File

@ -146,15 +146,14 @@ Alternatively, you can use a symlink called ``django`` that points to the
location of the branch's ``django`` package. If you want to switch back, just location of the branch's ``django`` package. If you want to switch back, just
change the symlink to point to the old code. change the symlink to point to the old code.
A third option is to use a `path file`_ (``<something>.pth``) which should A third option is to use a `path file`_ (``<something>.pth``). First, make sure
work on all systems (including Windows, which doesn't have symlinks there are no files, directories or symlinks named ``django`` in your
available). First, make sure there are no files, directories or symlinks named ``site-packages`` directory. Then create a text file named ``django.pth`` and
``django`` in your ``site-packages`` directory. Then create a text file named save it to your ``site-packages`` directory. That file should contain a path to
``django.pth`` and save it to your ``site-packages`` directory. That file your copy of Django on a single line and optional comments. Here is an example
should contain a path to your copy of Django on a single line and optional that points to multiple branches. Just uncomment the line for the branch you
comments. Here is an example that points to multiple branches. Just uncomment want to use ('Trunk' in this example) and make sure all other lines are
the line for the branch you want to use ('Trunk' in this example) and make commented::
sure all other lines are commented::
# Trunk is a svn checkout of: # Trunk is a svn checkout of:
# http://code.djangoproject.com/svn/django/trunk/ # http://code.djangoproject.com/svn/django/trunk/

15
docs/internals/contributing/writing-code/coding-style.txt
View File

@ -9,7 +9,7 @@ Python style
* Unless otherwise specified, follow :pep:`8`. * Unless otherwise specified, follow :pep:`8`.
You could use a tool like `pep8.py`_ to check for some problems in this You could use a tool like `pep8`_ to check for some problems in this
area, but remember that PEP 8 is only a guide, so respect the style of area, but remember that PEP 8 is only a guide, so respect the style of
the surrounding code as a primary goal. the surrounding code as a primary goal.
@ -171,9 +171,9 @@ That means that the ability for third parties to import the module at the top
level is incompatible with the ability to configure the settings object level is incompatible with the ability to configure the settings object
manually, or makes it very difficult in some circumstances. manually, or makes it very difficult in some circumstances.
Instead of the above code, a level of laziness or indirection must be used, Instead of the above code, a level of laziness or indirection must be used, such
such as `django.utils.functional.LazyObject``, ``django.utils.functional.lazy`` as :class:`django.utils.functional.LazyObject`,
or ``lambda``. :func:`django.utils.functional.lazy` or ``lambda``.
Miscellaneous Miscellaneous
------------- -------------
@ -181,10 +181,15 @@ Miscellaneous
* Mark all strings for internationalization; see the :doc:`i18n * Mark all strings for internationalization; see the :doc:`i18n
documentation </topics/i18n/index>` for details. documentation </topics/i18n/index>` for details.
* Remove ``import`` statements that are no longer used when you change code.
The most common tools for this task are `pyflakes`_ and `pylint`_.
* Please don't put your name in the code you contribute. Our policy is to * Please don't put your name in the code you contribute. Our policy is to
keep contributors' names in the ``AUTHORS`` file distributed with Django keep contributors' names in the ``AUTHORS`` file distributed with Django
-- not scattered throughout the codebase itself. Feel free to include a -- not scattered throughout the codebase itself. Feel free to include a
change to the ``AUTHORS`` file in your patch if you make more than a change to the ``AUTHORS`` file in your patch if you make more than a
single trivial change. single trivial change.
.. _pep8.py: http://pypi.python.org/pypi/pep8/ .. _pep8: http://pypi.python.org/pypi/pep8
.. _pyflakes: http://pypi.python.org/pypi/pyflakes
.. _pylint: http://pypi.python.org/pypi/pylint

14
docs/internals/contributing/writing-code/submitting-patches.txt
View File

@ -84,7 +84,7 @@ Patch style
Patches in ``git diff`` format are also acceptable. Patches in ``git diff`` format are also acceptable.
* When creating patches, always run ``svn diff`` from the top-level * When creating patches, always run ``svn diff`` from the top-level
``trunk`` directory -- i.e., the one that contains ``django``, ``docs``, ``trunk`` directory -- i.e. the one that contains ``django``, ``docs``,
``tests``, ``AUTHORS``, etc. This makes it easy for other people to ``tests``, ``AUTHORS``, etc. This makes it easy for other people to
apply your patches. apply your patches.
@ -101,8 +101,8 @@ Patch style
* The code required to fix a problem or add a feature is an essential part * The code required to fix a problem or add a feature is an essential part
of a patch, but it is not the only part. A good patch should also of a patch, but it is not the only part. A good patch should also
include a regression test to validate the behavior that has been fixed include a regression test to validate the behavior that has been fixed,
(and prevent the problem from arising again). to prevent the problem from arising again.
* If the code associated with a patch adds a new feature, or modifies * If the code associated with a patch adds a new feature, or modifies
behavior of an existing feature, the patch should also contain behavior of an existing feature, the patch should also contain
@ -130,13 +130,13 @@ Serving compressed or "minified" versions of javascript files is considered
best practice in this regard. best practice in this regard.
To that end, patches for javascript files should include both the original To that end, patches for javascript files should include both the original
code for future development (e.g. "foo.js"), and a compressed version for code for future development (e.g. ``foo.js``), and a compressed version for
production use (e.g. "foo.min.js"). Any links to the file in the codebase production use (e.g. ``foo.min.js``). Any links to the file in the codebase
should point to the compressed version. should point to the compressed version.
To simplify the process of providing optimized javascript code, Django To simplify the process of providing optimized javascript code, Django
includes a handy script which should be used to create a "minified" version. includes a handy script which should be used to create a "minified" version.
This script is located at ``/contrib/admin/media/js/compress.py``. This script is located at ``django/contrib/admin/static/js/compress.py``.
Behind the scenes, ``compress.py`` is a front-end for Google's Behind the scenes, ``compress.py`` is a front-end for Google's
`Closure Compiler`_ which is written in Java. However, the Closure Compiler `Closure Compiler`_ which is written in Java. However, the Closure Compiler
@ -148,7 +148,7 @@ The Closure Compiler library requires Java version 6 or higher (Java 1.6 or
higher on Mac OS X). Note that Mac OS X 10.5 and earlier did not ship with higher on Mac OS X). Note that Mac OS X 10.5 and earlier did not ship with
Java 1.6 by default, so it may be necessary to upgrade your Java installation Java 1.6 by default, so it may be necessary to upgrade your Java installation
before the tool will be functional. Also note that even after upgrading Java, before the tool will be functional. Also note that even after upgrading Java,
the default `/usr/bin/java` command may remain linked to the previous Java the default ``/usr/bin/java`` command may remain linked to the previous Java
binary, so relinking that command may be necessary as well. binary, so relinking that command may be necessary as well.
Please don't forget to run ``compress.py`` and include the ``diff`` of the Please don't forget to run ``compress.py`` and include the ``diff`` of the

25
docs/internals/contributing/writing-code/unit-tests.txt
View File

@ -3,13 +3,13 @@ Unit tests
========== ==========
Django comes with a test suite of its own, in the ``tests`` directory of the Django comes with a test suite of its own, in the ``tests`` directory of the
Django tarball. It's our policy to make sure all tests pass at all times. code base. It's our policy to make sure all tests pass at all times.
The tests cover: The tests cover:
* Models and the database API (``tests/modeltests/``). * Models and the database API (``tests/modeltests``),
* Everything else in core Django code (``tests/regressiontests``) * Everything else in core Django code (``tests/regressiontests``),
* Contrib apps (``django/contrib/<contribapp>/tests``, see below) * :ref:`contrib-apps` (``django/contrib/<app>/tests``).
We appreciate any and all contributions to the test suite! We appreciate any and all contributions to the test suite!
@ -105,8 +105,8 @@ internationalization, type:
./runtests.py --settings=path.to.settings generic_relations i18n ./runtests.py --settings=path.to.settings generic_relations i18n
How do you find out the names of individual tests? Look in How do you find out the names of individual tests? Look in
``tests/modeltests`` and ``tests/regressiontests`` -- each directory name ``tests/modeltests`` and ``tests/regressiontests`` — each directory name
there is the name of a test. there is the name of a test. Contrib app names are also valid test names.
If you just want to run a particular class of tests, you can specify a list of If you just want to run a particular class of tests, you can specify a list of
paths to individual test classes. For example, to run the ``TranslationTests`` paths to individual test classes. For example, to run the ``TranslationTests``
@ -150,16 +150,17 @@ associated tests will be skipped.
.. _memcached: http://www.danga.com/memcached/ .. _memcached: http://www.danga.com/memcached/
.. _gettext: http://www.gnu.org/software/gettext/manual/gettext.html .. _gettext: http://www.gnu.org/software/gettext/manual/gettext.html
.. _contrib-apps:
Contrib apps Contrib apps
------------ ------------
Tests for apps in ``django/contrib/`` go in their respective directories under Tests for contrib apps go in their respective directories under
``django/contrib/``, in a ``tests.py`` file. (You can split the tests over ``django/contrib``, in a ``tests.py`` file. You can split the tests over
multiple modules by using a ``tests`` directory in the normal Python way.) multiple modules by using a ``tests`` directory in the normal Python way.
For the tests to be found, a ``models.py`` file must exist (it doesn't For the tests to be found, a ``models.py`` file must exist, even if it's empty.
have to have anything in it). If you have URLs that need to be If you have URLs that need to be mapped, put them in ``tests/urls.py``.
mapped, put them in ``tests/urls.py``.
To run tests for just one contrib app (e.g. ``markup``), use the same To run tests for just one contrib app (e.g. ``markup``), use the same
method as above:: method as above::

14
docs/internals/contributing/writing-documentation.txt
View File

@ -9,10 +9,10 @@ possible.
Documentation changes generally come in two forms: Documentation changes generally come in two forms:
* General improvements -- Typo corrections, error fixes and better * General improvements: typo corrections, error fixes and better
explanations through clearer writing and more examples. explanations through clearer writing and more examples.
* New features -- Documentation of features that have been added to the * New features: documentation of features that have been added to the
framework since the last release. framework since the last release.
This section explains how writers can craft their documentation changes This section explains how writers can craft their documentation changes
@ -61,17 +61,13 @@ documentation:
* **email** -- no hyphen. * **email** -- no hyphen.
* **MySQL** * **MySQL**, **PostgreSQL**, **SQLite**
* **PostgreSQL**
* **Python** -- when referring to the language, capitalize Python. * **Python** -- when referring to the language, capitalize Python.
* **realize**, **customize**, **initialize**, etc. -- use the American * **realize**, **customize**, **initialize**, etc. -- use the American
"ize" suffix, not "ise." "ize" suffix, not "ise."
* **SQLite**
* **subclass** -- it's a single word without a hyphen, both as a verb * **subclass** -- it's a single word without a hyphen, both as a verb
("subclass that model") and as a noun ("create a subclass"). ("subclass that model") and as a noun ("create a subclass").
@ -168,10 +164,10 @@ Documenting new features
Our policy for new features is: Our policy for new features is:
**All documentation of new features should be written in a way that All documentation of new features should be written in a way that
clearly designates the features are only available in the Django clearly designates the features are only available in the Django
development version. Assume documentation readers are using the latest development version. Assume documentation readers are using the latest
release, not the development version.** release, not the development version.
Our preferred way for marking new features is by prefacing the features' Our preferred way for marking new features is by prefacing the features'
documentation with: "``.. versionadded:: X.Y``", followed by an optional one documentation with: "``.. versionadded:: X.Y``", followed by an optional one

372
docs/internals/deprecation.txt
View File

@ -3,232 +3,242 @@ Django Deprecation Timeline
=========================== ===========================
This document outlines when various pieces of Django will be removed, following This document outlines when various pieces of Django will be removed, following
their deprecation, as per the :ref:`Django deprecation policy their deprecation, as per the :ref:`deprecation policy
<internal-release-deprecation-policy>` <internal-release-deprecation-policy>`.
* 1.3 1.3
* ``AdminSite.root()``. This release will remove the old method for ---
hooking up admin URLs. This has been deprecated since the 1.1
release.
* Authentication backends need to define the boolean attributes * ``AdminSite.root()``. This release will remove the old method for
``supports_object_permissions`` and ``supports_anonymous_user``. hooking up admin URLs. This has been deprecated since the 1.1
The old backend style is deprecated since the 1.2 release. release.
* The :mod:`django.contrib.gis.db.backend` module, including the * Authentication backends need to define the boolean attributes
``SpatialBackend`` interface, is deprecated since the 1.2 release. ``supports_object_permissions`` and ``supports_anonymous_user``.
The old backend style is deprecated since the 1.2 release.
* 1.4 * The :mod:`django.contrib.gis.db.backend` module, including the
* ``CsrfResponseMiddleware``. This has been deprecated since the 1.2 ``SpatialBackend`` interface, is deprecated since the 1.2 release.
release, in favor of the template tag method for inserting the CSRF
token. ``CsrfMiddleware``, which combines ``CsrfResponseMiddleware``
and ``CsrfViewMiddleware``, is also deprecated.
* The old imports for CSRF functionality (``django.contrib.csrf.*``), 1.4
which moved to core in 1.2, will be removed. ---
* ``SMTPConnection``. The 1.2 release deprecated the ``SMTPConnection`` * ``CsrfResponseMiddleware``. This has been deprecated since the 1.2
class in favor of a generic E-mail backend API. release, in favor of the template tag method for inserting the CSRF
token. ``CsrfMiddleware``, which combines ``CsrfResponseMiddleware``
and ``CsrfViewMiddleware``, is also deprecated.
* The many to many SQL generation functions on the database backends * The old imports for CSRF functionality (``django.contrib.csrf.*``),
will be removed. which moved to core in 1.2, will be removed.
* The ability to use the ``DATABASE_*`` family of top-level settings to * ``SMTPConnection``. The 1.2 release deprecated the ``SMTPConnection``
define database connections will be removed. class in favor of a generic E-mail backend API.
* The ability to use shorthand notation to specify a database backend * The many to many SQL generation functions on the database backends
(i.e., ``sqlite3`` instead of ``django.db.backends.sqlite3``) will be will be removed.
removed.
* The ``get_db_prep_save``, ``get_db_prep_value`` and * The ability to use the ``DATABASE_*`` family of top-level settings to
``get_db_prep_lookup`` methods on Field were modified in 1.2 define database connections will be removed.
to support multiple databases. In 1.4, the support functions
that allow methods with the old prototype to continue
working will be removed.
* The ``Message`` model (in ``django.contrib.auth``), its related * The ability to use shorthand notation to specify a database backend
manager in the ``User`` model (``user.message_set``), and the (i.e., ``sqlite3`` instead of ``django.db.backends.sqlite3``) will be
associated methods (``user.message_set.create()`` and removed.
``user.get_and_delete_messages()``), which have
been deprecated since the 1.2 release, will be removed. The
:doc:`messages framework </ref/contrib/messages>` should be used
instead. The related ``messages`` variable returned by the
auth context processor will also be removed. Note that this
means that the admin application depends on the messages
context processor.
* Authentication backends need to support the ``obj`` parameter for * The ``get_db_prep_save``, ``get_db_prep_value`` and
permission checking. The ``supports_object_permissions`` variable ``get_db_prep_lookup`` methods on Field were modified in 1.2
is not checked any longer and can be removed. to support multiple databases. In 1.4, the support functions
that allow methods with the old prototype to continue
working will be removed.
* Authentication backends need to support the ``AnonymousUser`` * The ``Message`` model (in ``django.contrib.auth``), its related
being passed to all methods dealing with permissions. manager in the ``User`` model (``user.message_set``), and the
The ``supports_anonymous_user`` variable is not checked any associated methods (``user.message_set.create()`` and
longer and can be removed. ``user.get_and_delete_messages()``), which have
been deprecated since the 1.2 release, will be removed. The
:doc:`messages framework </ref/contrib/messages>` should be used
instead. The related ``messages`` variable returned by the
auth context processor will also be removed. Note that this
means that the admin application depends on the messages
context processor.
* The ability to specify a callable template loader rather than a * Authentication backends need to support the ``obj`` parameter for
``Loader`` class will be removed, as will the ``load_template_source`` permission checking. The ``supports_object_permissions`` variable
functions that are included with the built in template loaders for is not checked any longer and can be removed.
backwards compatibility. These have been deprecated since the 1.2
release.
* ``django.utils.translation.get_date_formats()`` and * Authentication backends need to support the ``AnonymousUser``
``django.utils.translation.get_partial_date_formats()``. These being passed to all methods dealing with permissions.
functions are replaced by the new locale aware formatting; use The ``supports_anonymous_user`` variable is not checked any
``django.utils.formats.get_format()`` to get the appropriate longer and can be removed.
formats.
* In ``django.forms.fields``: ``DEFAULT_DATE_INPUT_FORMATS``, * The ability to specify a callable template loader rather than a
``DEFAULT_TIME_INPUT_FORMATS`` and ``Loader`` class will be removed, as will the ``load_template_source``
``DEFAULT_DATETIME_INPUT_FORMATS``. Use functions that are included with the built in template loaders for
``django.utils.formats.get_format()`` to get the appropriate backwards compatibility. These have been deprecated since the 1.2
formats. release.
* The ability to use a function-based test runners will be removed, * ``django.utils.translation.get_date_formats()`` and
along with the ``django.test.simple.run_tests()`` test runner. ``django.utils.translation.get_partial_date_formats()``. These
functions are replaced by the new locale aware formatting; use
``django.utils.formats.get_format()`` to get the appropriate
formats.
* The ``views.feed()`` view and ``feeds.Feed`` class in * In ``django.forms.fields``: ``DEFAULT_DATE_INPUT_FORMATS``,
``django.contrib.syndication`` have been deprecated since the 1.2 ``DEFAULT_TIME_INPUT_FORMATS`` and
release. The class-based view ``views.Feed`` should be used instead. ``DEFAULT_DATETIME_INPUT_FORMATS``. Use
``django.utils.formats.get_format()`` to get the appropriate
formats.
* ``django.core.context_processors.auth``. This release will * The ability to use a function-based test runners will be removed,
remove the old method in favor of the new method in along with the ``django.test.simple.run_tests()`` test runner.
``django.contrib.auth.context_processors.auth``. This has been
deprecated since the 1.2 release.
* The ``postgresql`` database backend has been deprecated in favor of * The ``views.feed()`` view and ``feeds.Feed`` class in
the ``postgresql_psycopg2`` backend. ``django.contrib.syndication`` have been deprecated since the 1.2
release. The class-based view ``views.Feed`` should be used instead.
* The ``no`` language code has been deprecated in favor of the ``nb`` * ``django.core.context_processors.auth``. This release will
language code. remove the old method in favor of the new method in
``django.contrib.auth.context_processors.auth``. This has been
deprecated since the 1.2 release.
* Authentication backends need to define the boolean attribute * The ``postgresql`` database backend has been deprecated in favor of
``supports_inactive_user``. the ``postgresql_psycopg2`` backend.
* ``django.db.models.fields.XMLField`` will be removed. This was * The ``no`` language code has been deprecated in favor of the ``nb``
deprecated as part of the 1.3 release. An accelerated deprecation language code.
schedule has been used because the field hasn't performed any role
beyond that of a simple ``TextField`` since the removal of oldforms.
All uses of ``XMLField`` can be replaced with ``TextField``.
* 1.5 * Authentication backends need to define the boolean attribute
* The ``mod_python`` request handler has been deprecated since the 1.3 ``supports_inactive_user``.
release. The ``mod_wsgi`` handler should be used instead.
* The ``template`` attribute on :class:`~django.test.client.Response` * ``django.db.models.fields.XMLField`` will be removed. This was
objects returned by the :ref:`test client <test-client>` has been deprecated as part of the 1.3 release. An accelerated deprecation
deprecated since the 1.3 release. The schedule has been used because the field hasn't performed any role
:attr:`~django.test.client.Response.templates` attribute should be beyond that of a simple ``TextField`` since the removal of oldforms.
used instead. All uses of ``XMLField`` can be replaced with ``TextField``.
* The features of the :class:`django.test.simple.DjangoTestRunner` 1.5
(including fail-fast and Ctrl-C test termination) can now be provided ---
by the unittest-native :class:`TextTestRunner`. The
:class:`~django.test.simple.DjangoTestRunner` will be removed in
favor of using the unittest-native class.
* The undocumented function * The ``mod_python`` request handler has been deprecated since the 1.3
:func:`django.contrib.formtools.utils.security_hash` release. The ``mod_wsgi`` handler should be used instead.
is deprecated, in favor of :func:`django.contrib.formtools.utils.form_hmac`
* The function-based generic views have been deprecated in * The ``template`` attribute on :class:`~django.test.client.Response`
favor of their class-based cousins. The following modules objects returned by the :ref:`test client <test-client>` has been
will be removed: deprecated since the 1.3 release. The
:attr:`~django.test.client.Response.templates` attribute should be
used instead.
* :mod:`django.views.generic.create_update` * The features of the :class:`django.test.simple.DjangoTestRunner`
* :mod:`django.views.generic.date_based` (including fail-fast and Ctrl-C test termination) can now be provided
* :mod:`django.views.generic.list_detail` by the unittest-native :class:`TextTestRunner`. The
* :mod:`django.views.generic.simple` :class:`~django.test.simple.DjangoTestRunner` will be removed in
favor of using the unittest-native class.
* The :class:`~django.core.servers.basehttp.AdminMediaHandler` has * The undocumented function
been deprecated in favor of the :func:`django.contrib.formtools.utils.security_hash`
:class:`~django.contrib.staticfiles.handlers.StaticFilesHandler`. is deprecated, in favor of :func:`django.contrib.formtools.utils.form_hmac`
* The :ttag:`url` and :ttag:`ssi` template tags will be * The function-based generic views have been deprecated in
modified so that the first argument to each tag is a favor of their class-based cousins. The following modules
template variable, not an implied string. The new-style will be removed:
behavior is provided in the ``future`` template tag library.
* The :djadmin:`reset` and :djadmin:`sqlreset` management commands * :mod:`django.views.generic.create_update`
are deprecated. * :mod:`django.views.generic.date_based`
* :mod:`django.views.generic.list_detail`
* :mod:`django.views.generic.simple`
* Authentication backends need to support a inactive user * The :class:`~django.core.servers.basehttp.AdminMediaHandler` has
being passed to all methods dealing with permissions. been deprecated in favor of the
The ``supports_inactive_user`` variable is not checked any :class:`~django.contrib.staticfiles.handlers.StaticFilesHandler`.
longer and can be removed.
* :meth:`~django.contrib.gis.geos.GEOSGeometry.transform` will raise * The :ttag:`url` and :ttag:`ssi` template tags will be
a :class:`~django.contrib.gis.geos.GEOSException` when called modified so that the first argument to each tag is a
on a geometry with no SRID value. template variable, not an implied string. The new-style
behavior is provided in the ``future`` template tag library.
* :class:`~django.http.CompatCookie` will be removed in favor of * The :djadmin:`reset` and :djadmin:`sqlreset` management commands
:class:`~django.http.SimpleCookie`. are deprecated.
* :class:`django.core.context_processors.PermWrapper` and * Authentication backends need to support a inactive user
:class:`django.core.context_processors.PermLookupDict` being passed to all methods dealing with permissions.
will be moved to :class:`django.contrib.auth.context_processors.PermWrapper` The ``supports_inactive_user`` variable is not checked any
and :class:`django.contrib.auth.context_processors.PermLookupDict`, longer and can be removed.
respectively.
* The :setting:`MEDIA_URL` or :setting:`STATIC_URL` settings are * :meth:`~django.contrib.gis.geos.GEOSGeometry.transform` will raise
required to end with a trailing slash to ensure there is a consistent a :class:`~django.contrib.gis.geos.GEOSException` when called
way to combine paths in templates. on a geometry with no SRID value.
* 1.6 * :class:`~django.http.CompatCookie` will be removed in favor of
* The compatibility modules ``django.utils.copycompat`` and :class:`~django.http.SimpleCookie`.
``django.utils.hashcompat`` as well as the functions
``django.utils.itercompat.all`` and ``django.utils.itercompat.any``
have been deprecated since the 1.4 release. The native versions
should be used instead.
* The :func:`~django.views.decorators.csrf.csrf_response_exempt` and * :class:`django.core.context_processors.PermWrapper` and
:func:`~django.views.decorators.csrf.csrf_view_exempt` decorators will :class:`django.core.context_processors.PermLookupDict`
be removed. Since 1.4 ``csrf_response_exempt`` has been a no-op (it will be moved to :class:`django.contrib.auth.context_processors.PermWrapper`
returns the same function), and ``csrf_view_exempt`` has been a and :class:`django.contrib.auth.context_processors.PermLookupDict`,
synonym for ``django.views.decorators.csrf.csrf_exempt``, which should respectively.
be used to replace it.
* The :class:`~django.core.cache.backends.memcached.CacheClass` backend * The :setting:`MEDIA_URL` or :setting:`STATIC_URL` settings are
was split into two in Django 1.3 in order to introduce support for required to end with a trailing slash to ensure there is a consistent
PyLibMC. The historical :class:`~django.core.cache.backends.memcached.CacheClass` way to combine paths in templates.
is now an alias for :class:`~django.core.cache.backends.memcached.MemcachedCache`.
In Django 1.6, the historical alias will be removed.
* The UK-prefixed objects of ``django.contrib.localflavor.uk`` will only 1.6
be accessible through their new GB-prefixed names (GB is the correct ---
ISO 3166 code for United Kingdom). They have been deprecated since the
1.4 release.
* The :setting:`IGNORABLE_404_STARTS` and :setting:`IGNORABLE_404_ENDS` * The compatibility modules ``django.utils.copycompat`` and
settings have been superseded by :setting:`IGNORABLE_404_URLS` in ``django.utils.hashcompat`` as well as the functions
the 1.4 release. They will be removed. ``django.utils.itercompat.all`` and ``django.utils.itercompat.any``
have been deprecated since the 1.4 release. The native versions
should be used instead.
* The :doc:`form wizard </ref/contrib/formtools/form-wizard>` has been * The :func:`~django.views.decorators.csrf.csrf_response_exempt` and
refactored to use class based views with pluggable backends in 1.4. :func:`~django.views.decorators.csrf.csrf_view_exempt` decorators will
The previous implementation will be deprecated. be removed. Since 1.4 ``csrf_response_exempt`` has been a no-op (it
returns the same function), and ``csrf_view_exempt`` has been a
synonym for ``django.views.decorators.csrf.csrf_exempt``, which should
be used to replace it.
* Legacy ways of calling * The :class:`~django.core.cache.backends.memcached.CacheClass` backend
:func:`~django.views.decorators.cache.cache_page` will be removed. was split into two in Django 1.3 in order to introduce support for
PyLibMC. The historical :class:`~django.core.cache.backends.memcached.CacheClass`
is now an alias for :class:`~django.core.cache.backends.memcached.MemcachedCache`.
In Django 1.6, the historical alias will be removed.
* The backward-compatibility shim to automatically add a debug-false * The UK-prefixed objects of ``django.contrib.localflavor.uk`` will only
filter to the ``'mail_admins'`` logging handler will be removed. The be accessible through their new GB-prefixed names (GB is the correct
:setting:`LOGGING` setting should include this filter explicitly if ISO 3166 code for United Kingdom). They have been deprecated since the
it is desired. 1.4 release.
* The template tag * The :setting:`IGNORABLE_404_STARTS` and :setting:`IGNORABLE_404_ENDS`
:func:`django.contrib.admin.templatetags.adminmedia.admin_media_prefix` settings have been superseded by :setting:`IGNORABLE_404_URLS` in
was deprecated since Django 1.4 and will be removed in favor of the the 1.4 release. They will be removed.
generic static files handling.
* The builin truncation functions * The :doc:`form wizard </ref/contrib/formtools/form-wizard>` has been
:func:`django.utils.text.truncate_words` and refactored to use class based views with pluggable backends in 1.4.
:func:`django.utils.text.truncate_html_words` The previous implementation will be deprecated.
were deprecated since Django 1.4 and will be removed in favor
of the ``django.utils.text.Truncator`` class.
* 2.0 * Legacy ways of calling
* ``django.views.defaults.shortcut()``. This function has been moved :func:`~django.views.decorators.cache.cache_page` will be removed.
to ``django.contrib.contenttypes.views.shortcut()`` as part of the
goal of removing all ``django.contrib`` references from the core * The backward-compatibility shim to automatically add a debug-false
Django codebase. The old shortcut will be removed in the 2.0 filter to the ``'mail_admins'`` logging handler will be removed. The
release. :setting:`LOGGING` setting should include this filter explicitly if
it is desired.
* The template tag
:func:`django.contrib.admin.templatetags.adminmedia.admin_media_prefix`
was deprecated since Django 1.4 and will be removed in favor of the
generic static files handling.
* The builin truncation functions
:func:`django.utils.text.truncate_words` and
:func:`django.utils.text.truncate_html_words`
were deprecated since Django 1.4 and will be removed in favor
of the ``django.utils.text.Truncator`` class.
2.0
---
* ``django.views.defaults.shortcut()``. This function has been moved
to ``django.contrib.contenttypes.views.shortcut()`` as part of the
goal of removing all ``django.contrib`` references from the core
Django codebase. The old shortcut will be removed in the 2.0
release.

75
docs/internals/release-process.txt
View File

@ -7,30 +7,30 @@ Django's release process
Official releases Official releases
================= =================
Django's release numbering works as follows: Since version 1.0, Django's release numbering works as follows:
* Versions are numbered in the form ``A.B`` or ``A.B.C``. * Versions are numbered in the form ``A.B`` or ``A.B.C``.
* ``A`` is the *major version* number, which is only incremented for major * ``A`` is the *major version* number, which is only incremented for major
changes to Django, and these changes are not necessarily changes to Django, and these changes are not necessarily
backwards-compatible. That is, code you wrote for Django 6.0 may break backwards-compatible. That is, code you wrote for Django 1.2 may break
when we release Django 7.0. when we release Django 2.0.
* ``B`` is the *minor version* number, which is incremented for large yet * ``B`` is the *minor version* number, which is incremented for large yet
backwards compatible changes. Code written for Django 6.4 will continue backwards compatible changes. Code written for Django 1.2 will continue
to work under Django 6.5. to work under Django 1.3. Exceptions to this rule will be listed in the
release notes.
* ``C`` is the *micro version* number which, is incremented for bug and * ``C`` is the *micro version* number, which is incremented for bug and
security fixes. A new micro-release will always be 100% security fixes. A new micro-release will be 100% backwards-compatible with
backwards-compatible with the previous micro-release. the previous micro-release. The only exception is when a security issue
can't be fixed without breaking backwards-compatibility. If this happens,
the release notes will provide detailed upgrade instructions.
* In some cases, we'll make alpha, beta, or release candidate releases. * In some cases, we'll make alpha, beta, or release candidate releases.
These are of the form ``A.B alpha/beta/rc N``, which means the ``Nth`` These are of the form ``A.B alpha/beta/rc N``, which means the ``Nth``
alpha/beta/release candidate of version ``A.B``. alpha/beta/release candidate of version ``A.B``.
An exception to this version numbering scheme is the pre-1.0 Django code.
There's no guarantee of backwards-compatibility until the 1.0 release.
In Subversion, each Django release will be tagged under ``tags/releases``. If In Subversion, each Django release will be tagged under ``tags/releases``. If
it's necessary to release a bug fix release or a security release that doesn't it's necessary to release a bug fix release or a security release that doesn't
come from the trunk, we'll copy that tag to ``branches/releases`` to make the come from the trunk, we'll copy that tag to ``branches/releases`` to make the
@ -75,9 +75,9 @@ Micro releases
Micro releases (1.0.1, 1.0.2, 1.1.1, etc.) will be issued at least once half-way Micro releases (1.0.1, 1.0.2, 1.1.1, etc.) will be issued at least once half-way
between minor releases, and probably more often as needed. between minor releases, and probably more often as needed.
These releases will always be 100% compatible with the associated minor release These releases will be 100% compatible with the associated minor release, unless
-- the answer to "should I upgrade to the latest micro release?" will always be this is impossible for security reasons. So the answer to "should I upgrade to
"yes." the latest micro release?" will always be "yes."
Each minor release of Django will have a "release maintainer" appointed. This Each minor release of Django will have a "release maintainer" appointed. This
person will be responsible for making sure that bug fixes are applied to both person will be responsible for making sure that bug fixes are applied to both
@ -93,8 +93,20 @@ varying levels:
* The current development trunk will get new features and bug fixes * The current development trunk will get new features and bug fixes
requiring major refactoring. requiring major refactoring.
* All bug fixes applied to the trunk will also be applied to the last * Patches applied to the trunk will also be applied to the last minor
minor release, to be released as the next micro release. release, to be released as the next micro release, when they fix critical
problems:
* Security issues.
* Data-loss bugs.
* Crashing bugs.
* Major functionality bugs in newly-introduced features.
The rule of thumb is that fixes will be backported to the last minor
release for bugs that would have prevented a release in the first place.
* Security fixes will be applied to the current trunk and the previous two * Security fixes will be applied to the current trunk and the previous two
minor releases. minor releases.
@ -104,12 +116,12 @@ Django 1.3 and 1.4. At this point in time:
* Features will be added to development trunk, to be released as Django 1.4. * Features will be added to development trunk, to be released as Django 1.4.
* Bug fixes will be applied to a ``1.3.X`` branch, and released as 1.3.1, * Critical bug fixes will be applied to a ``1.3.X`` branch, and released as
1.3.2, etc. 1.3.1, 1.3.2, etc.
* Security releases will be applied to trunk, a ``1.3.X`` branch and a * Security fixes will be applied to trunk, a ``1.3.X`` branch and a
``1.2.X`` branch. Security fixes will trigger the release of ``1.3.1``, ``1.2.X`` branch. They will trigger the release of ``1.3.1``, ``1.2.1``,
``1.2.1``, etc. etc.
.. _release-process: .. _release-process:
@ -119,11 +131,11 @@ Release process
Django uses a time-based release schedule, with minor (i.e. 1.1, 1.2, etc.) Django uses a time-based release schedule, with minor (i.e. 1.1, 1.2, etc.)
releases every nine months, or more, depending on features. releases every nine months, or more, depending on features.
After each previous release (and after a suitable cooling-off period of a week After each release, and after a suitable cooling-off period of a few weeks, the
or two), the core development team will examine the landscape and announce a core development team will examine the landscape and announce a timeline for the
timeline for the next release. Most releases will be scheduled in the 6-9 month next release. Most releases will be scheduled in the 6-9 month range, but if we
range, but if we have bigger features to development we might schedule a longer have bigger features to development we might schedule a longer period to allow
period to allow for more ambitious work. for more ambitious work.
Release cycle Release cycle
------------- -------------
@ -174,10 +186,11 @@ and an rc complete with string freeze two weeks before the end of the schedule.
Bug-fix releases Bug-fix releases
---------------- ----------------
After a minor release (i.e 1.1), the previous release will go into bug-fix mode. After a minor release (e.g. 1.1), the previous release will go into bug-fix
mode.
A branch will be created of the form ``branches/releases/1.0.X`` to track A branch will be created of the form ``branches/releases/1.0.X`` to track
bug-fixes to the previous release. When possible, bugs fixed on trunk must bug-fixes to the previous release. Critical bugs fixed on trunk must
*also* be fixed on the bug-fix branch; this means that commits need to cleanly *also* be fixed on the bug-fix branch; this means that commits need to cleanly
separate bug fixes from feature additions. The developer who commits a fix to separate bug fixes from feature additions. The developer who commits a fix to
trunk will be responsible for also applying the fix to the current bug-fix trunk will be responsible for also applying the fix to the current bug-fix
@ -194,9 +207,9 @@ development will be happening in a bunch of places:
* On trunk, development towards 1.2 proceeds with small additions, bugs * On trunk, development towards 1.2 proceeds with small additions, bugs
fixes, etc. being checked in daily. fixes, etc. being checked in daily.
* On the branch "branches/releases/1.1.X", bug fixes found in the 1.1 * On the branch "branches/releases/1.1.X", fixes for critical bugs found in
release are checked in as needed. At some point, this branch will be the 1.1 release are checked in as needed. At some point, this branch will
released as "1.1.1", "1.1.2", etc. be released as "1.1.1", "1.1.2", etc.
* On the branch "branches/releases/1.0.X", security fixes are made if * On the branch "branches/releases/1.0.X", security fixes are made if
needed and released as "1.0.2", "1.0.3", etc. needed and released as "1.0.2", "1.0.3", etc.