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

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

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

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.

View File

@ -2,17 +2,34 @@
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.
@ -24,11 +41,12 @@ development:
* :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/

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

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 You can also review ``conf/locale/<locale>/formats.py``. This file describes
would: the date, time and numbers formatting particularities of your locale. See
:ref:`format-localization` for details.
The format files aren't managed by the use of Transifex. To change them, you
must :doc:`create a patch<writing-code/submitting-patches>` against the Django source tree, as for any code change:
* Create a diff against the current Subversion trunk. * Create a diff against the current Subversion trunk.
* Open a ticket in Django's ticket system, set its ``Component`` field * Open a ticket in Django's ticket system, set its ``Component`` field to
to ``Translations``, and attach the patch to it. See ``Translations``, and attach the patch to it.
:ref:`format-localization` for details.
.. _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/

View File

@ -2,11 +2,12 @@
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.
@ -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,

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/

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

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

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::

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

View File

@ -3,10 +3,12 @@ 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 * ``AdminSite.root()``. This release will remove the old method for
hooking up admin URLs. This has been deprecated since the 1.1 hooking up admin URLs. This has been deprecated since the 1.1
release. release.
@ -18,7 +20,9 @@ their deprecation, as per the :ref:`Django deprecation policy
* The :mod:`django.contrib.gis.db.backend` module, including the * The :mod:`django.contrib.gis.db.backend` module, including the
``SpatialBackend`` interface, is deprecated since the 1.2 release. ``SpatialBackend`` interface, is deprecated since the 1.2 release.
* 1.4 1.4
---
* ``CsrfResponseMiddleware``. This has been deprecated since the 1.2 * ``CsrfResponseMiddleware``. This has been deprecated since the 1.2
release, in favor of the template tag method for inserting the CSRF release, in favor of the template tag method for inserting the CSRF
token. ``CsrfMiddleware``, which combines ``CsrfResponseMiddleware`` token. ``CsrfMiddleware``, which combines ``CsrfResponseMiddleware``
@ -111,7 +115,9 @@ their deprecation, as per the :ref:`Django deprecation policy
beyond that of a simple ``TextField`` since the removal of oldforms. beyond that of a simple ``TextField`` since the removal of oldforms.
All uses of ``XMLField`` can be replaced with ``TextField``. All uses of ``XMLField`` can be replaced with ``TextField``.
* 1.5 1.5
---
* The ``mod_python`` request handler has been deprecated since the 1.3 * The ``mod_python`` request handler has been deprecated since the 1.3
release. The ``mod_wsgi`` handler should be used instead. release. The ``mod_wsgi`` handler should be used instead.
@ -174,7 +180,9 @@ their deprecation, as per the :ref:`Django deprecation policy
required to end with a trailing slash to ensure there is a consistent required to end with a trailing slash to ensure there is a consistent
way to combine paths in templates. way to combine paths in templates.
* 1.6 1.6
---
* The compatibility modules ``django.utils.copycompat`` and * The compatibility modules ``django.utils.copycompat`` and
``django.utils.hashcompat`` as well as the functions ``django.utils.hashcompat`` as well as the functions
``django.utils.itercompat.all`` and ``django.utils.itercompat.any`` ``django.utils.itercompat.all`` and ``django.utils.itercompat.any``
@ -226,7 +234,9 @@ their deprecation, as per the :ref:`Django deprecation policy
were deprecated since Django 1.4 and will be removed in favor were deprecated since Django 1.4 and will be removed in favor
of the ``django.utils.text.Truncator`` class. of the ``django.utils.text.Truncator`` class.
* 2.0 2.0
---
* ``django.views.defaults.shortcut()``. This function has been moved * ``django.views.defaults.shortcut()``. This function has been moved
to ``django.contrib.contenttypes.views.shortcut()`` as part of the to ``django.contrib.contenttypes.views.shortcut()`` as part of the
goal of removing all ``django.contrib`` references from the core goal of removing all ``django.contrib`` references from the core

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.