diff --git a/docs/internals/contributing/bugs-and-features.txt b/docs/internals/contributing/bugs-and-features.txt index 47cb580aff..2ab3d9236c 100644 --- a/docs/internals/contributing/bugs-and-features.txt +++ b/docs/internals/contributing/bugs-and-features.txt @@ -2,14 +2,14 @@ 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: * Check that someone hasn't already filed the bug or feature request by `searching`_ or running `custom queries`_ in the ticket tracker. * 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. 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`_. * 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`_. .. _reporting-bugs: @@ -33,19 +33,19 @@ particular: * **Do** read the :doc:`FAQ ` to see if your issue might be a well-known question. - * **Do** ask on `django-users`_ *first* if you're not sure if what you're - seeing is a bug. + * **Do** ask on `django-users`_ or `#django`_ *first* if you're not sure if + what you're seeing is a bug. - * **Do** write complete, reproducible, specific bug reports. Include as - much information as you possibly can, complete with code snippets, test - cases, etc. This means including a clear, concise description of the - problem, and a clear set of instructions for replicating the problem. - A minimal example that illustrates the bug in a nice small test case - is the best possible bug report. + * **Do** write complete, reproducible, specific bug reports. You must + include a clear, concise description of the problem, and a set of + instructions for replicating it. Add as much debug information as you can: + code snippets, test cases, exception backtraces, screenshots, etc. A nice + small test case is the best way to report a bug, as it gives us an easy + way to confirm the bug quickly. - * **Don't** post to django-developers just to announce that you have filed - a bug report. All the tickets are mailed to another list - (`django-updates`_), which is tracked by developers and interested + * **Don't** post to `django-developers`_ just to announce that you have + filed a bug report. All the tickets are mailed to another list, + `django-updates`_, which is tracked by developers and interested community members; we see them as they are filed. 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 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 - tracker. It'll get read more closely if it's on the mailing list. + * Make sure the feature actually requires changes in Django's core. If your + 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 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 useful. - * Don't use the ticket system to make large-scale feature requests. - We like to discuss any big changes to Django's core on the - `django-developers`_ list before actually working on them. +If core developers agree on the feature, then it's appropriate to create a +ticket. Include a link the discussion on `django-developers`_ in the ticket +description. 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 multiple developers, we're always happy to give you an experimental branch in 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`. .. _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 into reality." -Although these votes on django-developers are informal, they'll be taken very -seriously. After a suitable voting period, if an obvious consensus arises -we'll follow the votes. +Although these votes on `django-developers`_ are informal, they'll be taken very +seriously. After a suitable voting period, if an obvious consensus arises we'll +follow the votes. However, consensus is not always possible. If consensus cannot be reached, or if the discussion towards a consensus fizzles out without a concrete decision, @@ -175,7 +182,7 @@ committers -- may be held in private. .. _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-users: http://groups.google.com/group/django-users -.. _`#django`: irc://irc.freenode.net/django +.. _#django: irc://irc.freenode.net/django diff --git a/docs/internals/contributing/committing-code.txt b/docs/internals/contributing/committing-code.txt index 601d1a0ef2..ffdff60717 100644 --- a/docs/internals/contributing/committing-code.txt +++ b/docs/internals/contributing/committing-code.txt @@ -28,11 +28,9 @@ Partial committers in question is likely to be sufficient. Decisions on new committers will follow the process explained in -:ref:`how-we-make-decisions`. - -To request commit access, please contact an existing committer privately. -Public requests for commit access are potential flame-war starters, and -will be ignored. +:ref:`how-we-make-decisions`. To request commit access, please contact an +existing committer privately. Public requests for commit access are potential +flame-war starters, and will be ignored. Committing guidelines --------------------- @@ -69,12 +67,12 @@ repository: * Separate bug fixes from feature changes. - Bug fixes need to be added to the current bugfix branch (e.g. the - ``1.0.X`` branch) as well as the current trunk. + Bug fixes need to be added to the current bugfix branch as well as the + current trunk. * If your commit closes a ticket in the Django `ticket tracker`_, begin your commit message with the text "Fixed #abc", where "abc" is the - number of the ticket your commit fixes. Example: "Fixed #123 -- 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 message in that format will automatically close the referenced ticket and post a comment to it with the full commit message. @@ -83,7 +81,7 @@ repository: first, then the "Fixed #abc." For example: "magic-removal: Fixed #123 -- Added whizbang feature." - For the curious: We're using a `Trac post-commit hook`_ for this. + 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 @@ -111,8 +109,8 @@ discovered, please follow these guidelines: * If the original author can't be reached (within a reasonable amount of time -- a day or so) and the problem is severe -- crashing bug, - major test failures, etc -- then ask for objections on django-dev - then revert if there are none. + major test failures, etc -- then ask for objections on the + `django-developers`_ mailing list then revert if there are none. * If the problem is small (a feature commit after feature freeze, say), wait it out. diff --git a/docs/internals/contributing/index.txt b/docs/internals/contributing/index.txt index b326ad90b9..0c2e77cbbf 100644 --- a/docs/internals/contributing/index.txt +++ b/docs/internals/contributing/index.txt @@ -2,33 +2,51 @@ 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* 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 development: - * 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`_. - - * :doc:`Report bugs and request features` in our - `ticket tracker`_. + * :doc:`Report bugs ` in our `ticket tracker`_. * Join the `django-developers`_ mailing list and share your ideas for how to improve Django. We're always open to suggestions. - * :doc:`Submit patches` for new and/or + * :doc:`Submit patches ` for new and/or fixed behavior. If you're looking for an easy way to start contributing to Django have a look at the `easy pickings`_ tickets. - * :doc:`Improve the documentation` or - :doc:`write unit tests`. + * :doc:`Improve the documentation ` or + :doc:`write unit tests `. - * :doc:`Triage tickets` that have been created by other - users. + * :doc:`Triage tickets and review patches ` created by + other users. -... and many more ways! Really, **ANYONE** can do something to help make -Django better and greater. Browse the following sections to find out how: +Really, **ANYONE** can do something to help make Django better and greater! + +Browse the following sections to find out how: .. toctree:: :maxdepth: 2 @@ -41,8 +59,11 @@ Django better and greater. Browse the following sections to find out how: translations 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 .. _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 -.. _`register it here`: http://www.djangoproject.com/community/add/blogs/ +.. _easy pickings: http://code.djangoproject.com/query?status=!closed&easy=1 diff --git a/docs/internals/contributing/new-contributors.txt b/docs/internals/contributing/new-contributors.txt index f1673b3618..abf3f1c94e 100644 --- a/docs/internals/contributing/new-contributors.txt +++ b/docs/internals/contributing/new-contributors.txt @@ -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 to get started? This is the section for you. -* **Pick a subject area that you care about, that you are familiar with, or - that you want to learn about** +First steps +----------- - 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. +Start with these easy tasks to discover Django's development process. * **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 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 @@ -44,7 +43,30 @@ to get started? This is the section for you. :doc:`writing-documentation`, in particular the tips for :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. 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 tests altogether. -.. 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 +.. _easy pickings: http://code.djangoproject.com/query?status=!closed&easy=1 .. _new-contributors-faq: @@ -114,7 +130,7 @@ FAQ 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 - 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 #django-dev IRC channel. @@ -130,8 +146,6 @@ FAQ Design Decision Needed requires consensus about the right solution. At the 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 - 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 solutions. - -.. _`easy pickings`: http://code.djangoproject.com/query?status=!closed&easy=1 diff --git a/docs/internals/contributing/translations.txt b/docs/internals/contributing/translations.txt index ade04e6c3c..fe38adc9d7 100644 --- a/docs/internals/contributing/translations.txt +++ b/docs/internals/contributing/translations.txt @@ -3,16 +3,21 @@ Submitting and maintaining translations ======================================= Various parts of Django, such as the admin site and validation error messages, -are internationalized. This means they display different text depending on a -user's language setting. For this, Django uses the same internationalization -infrastructure available to Django applications described in the +are internationalized. This means they display different text depending on each +user's language setting. For this, Django uses the same internationalization and +localization infrastructure available to Django applications, described in the :doc:`i18n documentation`. -These translations are contributed by Django users worldwide. If you find an -incorrect translation or 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: +Internationalization +-------------------- + +Translations are contributed by Django users worldwide. The translation work is +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. @@ -20,7 +25,7 @@ to do: * 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 -- request a new team by clicking on the "Request a new team" button and select the appropriate language. @@ -37,24 +42,27 @@ to do: Each of the contrib apps also have a resource (prefixed with "contrib"). .. note:: - For more information about how to use Transifex, see the - `Transifex Help`_ + For more information about how to use Transifex, read the + `Transifex User Guide`_. - * Optionally, review and update the ``conf/locale//formats.py`` - file to describe the date, time and numbers formatting particularities - of your locale. These files aren't covered by the use of Transifex and - require a patch against the Django source tree, just as a code change - would: +Localization +------------ - * Create a diff against the current Subversion trunk. +You can also review ``conf/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 - to ``Translations``, and attach the patch to it. 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` against the Django source tree, as for any code change: + + * 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/ +.. _Django i18n mailing list: http://groups.google.com/group/django-i18n/ .. _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/ -.. _Transifex Help: http://help.transifex.net/ +.. _translation teams: http://www.transifex.net/projects/p/django/teams/ +.. _Transifex User Guide: http://help.transifex.net/ diff --git a/docs/internals/contributing/triaging-tickets.txt b/docs/internals/contributing/triaging-tickets.txt index a59d01b22f..97ac78e386 100644 --- a/docs/internals/contributing/triaging-tickets.txt +++ b/docs/internals/contributing/triaging-tickets.txt @@ -2,16 +2,17 @@ Triaging tickets ================ -Django uses Trac_ for managing our progress, and Trac is a community-tended -garden of the bugs people have found and the features people would like to see -added. As in any garden, sometimes there are weeds to be pulled and sometimes -there are flowers and vegetables that need picking. We need your help to sort -out one from the other, and in the end we all benefit together. +Django uses Trac_ for managing the work on the code base. Trac is a +community-tended garden of the bugs people have found and the features people +would like to see added. As in any garden, sometimes there are weeds to be +pulled and sometimes there are flowers and vegetables that need picking. We need +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 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 -intentions--fertilize the weeds and poison the roses. It's the job of the +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 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 contributing members. @@ -39,8 +40,8 @@ tickets have patches, but those patches don't meet all the requirements of a :ref:`good patch`. 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 -regularly, but more help is always appreciated. +users. The core team and several community members work on this regularly, but +more help is always appreciated. Most of the workflow is based around the concept of a ticket's :ref:`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` for "My ticket has been in DDN forever! What should I do?" -This stage will generally only be used for feature -requests. It can also be used for issues that *might* be bugs, depending on -opinion or interpretation. Obvious bugs (such as crashes, incorrect query -results, or non-compliance with a standard) skip this stage and move straight -to "Accepted". +This stage will often be used for feature requests. It can also be used for +issues that *might* be bugs, depending on opinion or interpretation. Obvious +bugs (such as crashes, incorrect query results, or non-compliance with a +standard) skip this stage and move straight to "Accepted". 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 ready for checkin. This could mean the patch no longer applies cleanly, there is a flaw in the implementation, or that the code - doesn't meet our standards." + doesn't meet our standards. * Easy pickings 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 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 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 start or join in discussions of "wontfix" tickets on the django-developers_ mailing list, but please do not reopen tickets - closed as "wontfix" by core developers. + closed as "wontfix" by a :doc:`core developer`. * 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 review a patch that you submit. - * Please **don't** reverse a decision that has been made by a core - developer. If you disagree with a decision that has been made, - please post a message to `django-developers`_. + * 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, please post a message to `django-developers`_. * 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, diff --git a/docs/internals/contributing/writing-code/branch-policy.txt b/docs/internals/contributing/writing-code/branch-policy.txt index 940b96f7ac..8bda15a3d4 100644 --- a/docs/internals/contributing/writing-code/branch-policy.txt +++ b/docs/internals/contributing/writing-code/branch-policy.txt @@ -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 change the symlink to point to the old code. -A third option is to use a `path file`_ (``.pth``) which should -work on all systems (including Windows, which doesn't have symlinks -available). First, make sure there are no files, directories or symlinks named -``django`` in your ``site-packages`` directory. Then create a text file named -``django.pth`` and save it to your ``site-packages`` directory. That file -should contain a path to your copy of Django on a single line and optional -comments. Here is an example that points to multiple branches. Just uncomment -the line for the branch you want to use ('Trunk' in this example) and make -sure all other lines are commented:: +A third option is to use a `path file`_ (``.pth``). First, make sure +there are no files, directories or symlinks named ``django`` in your +``site-packages`` directory. Then create a text file named ``django.pth`` and +save it to your ``site-packages`` directory. That file should contain a path to +your copy of Django on a single line and optional comments. Here is an example +that points to multiple branches. Just uncomment the line for the branch you +want to use ('Trunk' in this example) and make sure all other lines are +commented:: # Trunk is a svn checkout of: # http://code.djangoproject.com/svn/django/trunk/ diff --git a/docs/internals/contributing/writing-code/coding-style.txt b/docs/internals/contributing/writing-code/coding-style.txt index 616550dcef..7a07735616 100644 --- a/docs/internals/contributing/writing-code/coding-style.txt +++ b/docs/internals/contributing/writing-code/coding-style.txt @@ -9,7 +9,7 @@ Python style * 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 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 manually, or makes it very difficult in some circumstances. -Instead of the above code, a level of laziness or indirection must be used, -such as `django.utils.functional.LazyObject``, ``django.utils.functional.lazy`` -or ``lambda``. +Instead of the above code, a level of laziness or indirection must be used, such +as :class:`django.utils.functional.LazyObject`, +:func:`django.utils.functional.lazy` or ``lambda``. Miscellaneous ------------- @@ -181,10 +181,15 @@ Miscellaneous * Mark all strings for internationalization; see the :doc:`i18n documentation ` 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 keep contributors' names in the ``AUTHORS`` file distributed with Django -- not scattered throughout the codebase itself. Feel free to include a change to the ``AUTHORS`` file in your patch if you make more than a single trivial change. -.. _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 diff --git a/docs/internals/contributing/writing-code/submitting-patches.txt b/docs/internals/contributing/writing-code/submitting-patches.txt index 4eb74e1b1e..8190206106 100644 --- a/docs/internals/contributing/writing-code/submitting-patches.txt +++ b/docs/internals/contributing/writing-code/submitting-patches.txt @@ -84,7 +84,7 @@ Patch style Patches in ``git diff`` format are also acceptable. * When creating patches, always run ``svn diff`` from the top-level - ``trunk`` directory -- i.e., the one that contains ``django``, ``docs``, + ``trunk`` directory -- i.e. the one that contains ``django``, ``docs``, ``tests``, ``AUTHORS``, etc. This makes it easy for other people to apply your patches. @@ -101,8 +101,8 @@ Patch style * The code required to fix a problem or add a feature is an essential part of a patch, but it is not the only part. A good patch should also - include a regression test to validate the behavior that has been fixed - (and prevent the problem from arising again). + include a regression test to validate the behavior that has been fixed, + to prevent the problem from arising again. * If the code associated with a patch adds a new feature, or modifies behavior of an existing feature, the patch should also contain @@ -130,13 +130,13 @@ Serving compressed or "minified" versions of javascript files is considered best practice in this regard. To that end, patches for javascript files should include both the original -code for future development (e.g. "foo.js"), and a compressed version for -production use (e.g. "foo.min.js"). Any links to the file in the codebase +code for future development (e.g. ``foo.js``), and a compressed version for +production use (e.g. ``foo.min.js``). Any links to the file in the codebase should point to the compressed version. To simplify the process of providing optimized javascript code, Django includes a handy script which should be used to create a "minified" version. -This script is located at ``/contrib/admin/media/js/compress.py``. +This script is located at ``django/contrib/admin/static/js/compress.py``. Behind the scenes, ``compress.py`` is a front-end for Google's `Closure Compiler`_ which is written in Java. However, the Closure Compiler @@ -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 Java 1.6 by default, so it may be necessary to upgrade your Java installation before the tool will be functional. Also note that even after upgrading Java, -the default `/usr/bin/java` command may remain linked to the previous Java +the default ``/usr/bin/java`` command may remain linked to the previous Java binary, so relinking that command may be necessary as well. Please don't forget to run ``compress.py`` and include the ``diff`` of the diff --git a/docs/internals/contributing/writing-code/unit-tests.txt b/docs/internals/contributing/writing-code/unit-tests.txt index 3789172f99..cffcbd9371 100644 --- a/docs/internals/contributing/writing-code/unit-tests.txt +++ b/docs/internals/contributing/writing-code/unit-tests.txt @@ -3,13 +3,13 @@ Unit tests ========== Django comes with a test suite of its own, in the ``tests`` directory of the -Django tarball. It's our policy to make sure all tests pass at all times. +code base. It's our policy to make sure all tests pass at all times. The tests cover: - * Models and the database API (``tests/modeltests/``). - * Everything else in core Django code (``tests/regressiontests``) - * Contrib apps (``django/contrib//tests``, see below) + * Models and the database API (``tests/modeltests``), + * Everything else in core Django code (``tests/regressiontests``), + * :ref:`contrib-apps` (``django/contrib//tests``). 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 How do you find out the names of individual tests? Look in -``tests/modeltests`` and ``tests/regressiontests`` -- each directory name -there is the name of a test. +``tests/modeltests`` and ``tests/regressiontests`` — each directory name +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 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/ .. _gettext: http://www.gnu.org/software/gettext/manual/gettext.html +.. _contrib-apps: + Contrib apps ------------ -Tests for apps in ``django/contrib/`` go in their respective directories under -``django/contrib/``, in a ``tests.py`` file. (You can split the tests over -multiple modules by using a ``tests`` directory in the normal Python way.) +Tests for contrib apps go in their respective directories under +``django/contrib``, in a ``tests.py`` file. You can split the tests over +multiple modules by using a ``tests`` directory in the normal Python way. -For the tests to be found, a ``models.py`` file must exist (it doesn't -have to have anything in it). If you have URLs that need to be -mapped, put them in ``tests/urls.py``. +For the tests to be found, a ``models.py`` file must exist, even if it's empty. +If you have URLs that need to be mapped, put them in ``tests/urls.py``. To run tests for just one contrib app (e.g. ``markup``), use the same method as above:: diff --git a/docs/internals/contributing/writing-documentation.txt b/docs/internals/contributing/writing-documentation.txt index f6d6c6f108..cf8e6b41a2 100644 --- a/docs/internals/contributing/writing-documentation.txt +++ b/docs/internals/contributing/writing-documentation.txt @@ -9,10 +9,10 @@ possible. 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. - * 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. This section explains how writers can craft their documentation changes @@ -61,17 +61,13 @@ documentation: * **email** -- no hyphen. - * **MySQL** - - * **PostgreSQL** + * **MySQL**, **PostgreSQL**, **SQLite** * **Python** -- when referring to the language, capitalize Python. * **realize**, **customize**, **initialize**, etc. -- use the American "ize" suffix, not "ise." - * **SQLite** - * **subclass** -- it's a single word without a hyphen, both as a verb ("subclass that model") and as a noun ("create a subclass"). @@ -168,10 +164,10 @@ Documenting new features 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 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' documentation with: "``.. versionadded:: X.Y``", followed by an optional one diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt index 3639cc2fd0..105b39e937 100644 --- a/docs/internals/deprecation.txt +++ b/docs/internals/deprecation.txt @@ -3,232 +3,242 @@ Django Deprecation Timeline =========================== 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 +`. - * 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. +1.3 +--- - * Authentication backends need to define the boolean attributes - ``supports_object_permissions`` and ``supports_anonymous_user``. - The old backend style is deprecated since the 1.2 release. + * ``AdminSite.root()``. This release will remove the old method for + hooking up admin URLs. This has been deprecated since the 1.1 + release. - * The :mod:`django.contrib.gis.db.backend` module, including the - ``SpatialBackend`` interface, is deprecated since the 1.2 release. + * Authentication backends need to define the boolean attributes + ``supports_object_permissions`` and ``supports_anonymous_user``. + The old backend style is deprecated since the 1.2 release. - * 1.4 - * ``CsrfResponseMiddleware``. This has been deprecated since the 1.2 - release, in favor of the template tag method for inserting the CSRF - token. ``CsrfMiddleware``, which combines ``CsrfResponseMiddleware`` - and ``CsrfViewMiddleware``, is also deprecated. + * The :mod:`django.contrib.gis.db.backend` module, including the + ``SpatialBackend`` interface, is deprecated since the 1.2 release. - * The old imports for CSRF functionality (``django.contrib.csrf.*``), - which moved to core in 1.2, will be removed. +1.4 +--- - * ``SMTPConnection``. The 1.2 release deprecated the ``SMTPConnection`` - class in favor of a generic E-mail backend API. + * ``CsrfResponseMiddleware``. This has been deprecated since the 1.2 + 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 - will be removed. + * The old imports for CSRF functionality (``django.contrib.csrf.*``), + which moved to core in 1.2, will be removed. - * The ability to use the ``DATABASE_*`` family of top-level settings to - define database connections will be removed. + * ``SMTPConnection``. The 1.2 release deprecated the ``SMTPConnection`` + class in favor of a generic E-mail backend API. - * The ability to use shorthand notation to specify a database backend - (i.e., ``sqlite3`` instead of ``django.db.backends.sqlite3``) will be - removed. + * The many to many SQL generation functions on the database backends + will be removed. - * The ``get_db_prep_save``, ``get_db_prep_value`` and - ``get_db_prep_lookup`` methods on Field were modified in 1.2 - to support multiple databases. In 1.4, the support functions - that allow methods with the old prototype to continue - working will be removed. + * The ability to use the ``DATABASE_*`` family of top-level settings to + define database connections will be removed. - * The ``Message`` model (in ``django.contrib.auth``), its related - manager in the ``User`` model (``user.message_set``), and the - associated methods (``user.message_set.create()`` and - ``user.get_and_delete_messages()``), which have - been deprecated since the 1.2 release, will be removed. The - :doc:`messages framework ` 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 use shorthand notation to specify a database backend + (i.e., ``sqlite3`` instead of ``django.db.backends.sqlite3``) will be + removed. - * Authentication backends need to support the ``obj`` parameter for - permission checking. The ``supports_object_permissions`` variable - is not checked any longer and can be removed. + * The ``get_db_prep_save``, ``get_db_prep_value`` and + ``get_db_prep_lookup`` methods on Field were modified in 1.2 + 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`` - being passed to all methods dealing with permissions. - The ``supports_anonymous_user`` variable is not checked any - longer and can be removed. + * The ``Message`` model (in ``django.contrib.auth``), its related + manager in the ``User`` model (``user.message_set``), and the + associated methods (``user.message_set.create()`` and + ``user.get_and_delete_messages()``), which have + been deprecated since the 1.2 release, will be removed. The + :doc:`messages framework ` 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 - ``Loader`` class will be removed, as will the ``load_template_source`` - functions that are included with the built in template loaders for - backwards compatibility. These have been deprecated since the 1.2 - release. + * Authentication backends need to support the ``obj`` parameter for + permission checking. The ``supports_object_permissions`` variable + is not checked any longer and can be removed. - * ``django.utils.translation.get_date_formats()`` and - ``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. + * Authentication backends need to support the ``AnonymousUser`` + being passed to all methods dealing with permissions. + The ``supports_anonymous_user`` variable is not checked any + longer and can be removed. - * In ``django.forms.fields``: ``DEFAULT_DATE_INPUT_FORMATS``, - ``DEFAULT_TIME_INPUT_FORMATS`` and - ``DEFAULT_DATETIME_INPUT_FORMATS``. Use - ``django.utils.formats.get_format()`` to get the appropriate - formats. + * The ability to specify a callable template loader rather than a + ``Loader`` class will be removed, as will the ``load_template_source`` + functions that are included with the built in template loaders for + backwards compatibility. These have been deprecated since the 1.2 + release. - * The ability to use a function-based test runners will be removed, - along with the ``django.test.simple.run_tests()`` test runner. + * ``django.utils.translation.get_date_formats()`` and + ``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 - ``django.contrib.syndication`` have been deprecated since the 1.2 - release. The class-based view ``views.Feed`` should be used instead. + * In ``django.forms.fields``: ``DEFAULT_DATE_INPUT_FORMATS``, + ``DEFAULT_TIME_INPUT_FORMATS`` and + ``DEFAULT_DATETIME_INPUT_FORMATS``. Use + ``django.utils.formats.get_format()`` to get the appropriate + formats. - * ``django.core.context_processors.auth``. This release will - 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. + * The ability to use a function-based test runners will be removed, + along with the ``django.test.simple.run_tests()`` test runner. - * The ``postgresql`` database backend has been deprecated in favor of - the ``postgresql_psycopg2`` backend. + * The ``views.feed()`` view and ``feeds.Feed`` class in + ``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`` - language code. + * ``django.core.context_processors.auth``. This release will + 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 - ``supports_inactive_user``. + * The ``postgresql`` database backend has been deprecated in favor of + the ``postgresql_psycopg2`` backend. - * ``django.db.models.fields.XMLField`` will be removed. This was - deprecated as part of the 1.3 release. An accelerated deprecation - 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``. + * The ``no`` language code has been deprecated in favor of the ``nb`` + language code. - * 1.5 - * The ``mod_python`` request handler has been deprecated since the 1.3 - release. The ``mod_wsgi`` handler should be used instead. + * Authentication backends need to define the boolean attribute + ``supports_inactive_user``. - * The ``template`` attribute on :class:`~django.test.client.Response` - objects returned by the :ref:`test client ` has been - deprecated since the 1.3 release. The - :attr:`~django.test.client.Response.templates` attribute should be - used instead. + * ``django.db.models.fields.XMLField`` will be removed. This was + deprecated as part of the 1.3 release. An accelerated deprecation + 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``. - * The features of the :class:`django.test.simple.DjangoTestRunner` - (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. +1.5 +--- - * The undocumented function - :func:`django.contrib.formtools.utils.security_hash` - is deprecated, in favor of :func:`django.contrib.formtools.utils.form_hmac` + * The ``mod_python`` request handler has been deprecated since the 1.3 + release. The ``mod_wsgi`` handler should be used instead. - * The function-based generic views have been deprecated in - favor of their class-based cousins. The following modules - will be removed: + * The ``template`` attribute on :class:`~django.test.client.Response` + objects returned by the :ref:`test client ` has been + deprecated since the 1.3 release. The + :attr:`~django.test.client.Response.templates` attribute should be + used instead. - * :mod:`django.views.generic.create_update` - * :mod:`django.views.generic.date_based` - * :mod:`django.views.generic.list_detail` - * :mod:`django.views.generic.simple` + * The features of the :class:`django.test.simple.DjangoTestRunner` + (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 :class:`~django.core.servers.basehttp.AdminMediaHandler` has - been deprecated in favor of the - :class:`~django.contrib.staticfiles.handlers.StaticFilesHandler`. + * The undocumented function + :func:`django.contrib.formtools.utils.security_hash` + is deprecated, in favor of :func:`django.contrib.formtools.utils.form_hmac` - * The :ttag:`url` and :ttag:`ssi` template tags will be - modified so that the first argument to each tag is a - template variable, not an implied string. The new-style - behavior is provided in the ``future`` template tag library. + * The function-based generic views have been deprecated in + favor of their class-based cousins. The following modules + will be removed: - * The :djadmin:`reset` and :djadmin:`sqlreset` management commands - are deprecated. + * :mod:`django.views.generic.create_update` + * :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 - being passed to all methods dealing with permissions. - The ``supports_inactive_user`` variable is not checked any - longer and can be removed. + * The :class:`~django.core.servers.basehttp.AdminMediaHandler` has + been deprecated in favor of the + :class:`~django.contrib.staticfiles.handlers.StaticFilesHandler`. - * :meth:`~django.contrib.gis.geos.GEOSGeometry.transform` will raise - a :class:`~django.contrib.gis.geos.GEOSException` when called - on a geometry with no SRID value. + * The :ttag:`url` and :ttag:`ssi` template tags will be + modified so that the first argument to each tag is a + 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 - :class:`~django.http.SimpleCookie`. + * The :djadmin:`reset` and :djadmin:`sqlreset` management commands + are deprecated. - * :class:`django.core.context_processors.PermWrapper` and - :class:`django.core.context_processors.PermLookupDict` - will be moved to :class:`django.contrib.auth.context_processors.PermWrapper` - and :class:`django.contrib.auth.context_processors.PermLookupDict`, - respectively. + * Authentication backends need to support a inactive user + being passed to all methods dealing with permissions. + The ``supports_inactive_user`` variable is not checked any + longer and can be removed. - * The :setting:`MEDIA_URL` or :setting:`STATIC_URL` settings are - required to end with a trailing slash to ensure there is a consistent - way to combine paths in templates. + * :meth:`~django.contrib.gis.geos.GEOSGeometry.transform` will raise + a :class:`~django.contrib.gis.geos.GEOSException` when called + on a geometry with no SRID value. - * 1.6 - * The compatibility modules ``django.utils.copycompat`` and - ``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. + * :class:`~django.http.CompatCookie` will be removed in favor of + :class:`~django.http.SimpleCookie`. - * The :func:`~django.views.decorators.csrf.csrf_response_exempt` and - :func:`~django.views.decorators.csrf.csrf_view_exempt` decorators will - 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. + * :class:`django.core.context_processors.PermWrapper` and + :class:`django.core.context_processors.PermLookupDict` + will be moved to :class:`django.contrib.auth.context_processors.PermWrapper` + and :class:`django.contrib.auth.context_processors.PermLookupDict`, + respectively. - * The :class:`~django.core.cache.backends.memcached.CacheClass` backend - 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 :setting:`MEDIA_URL` or :setting:`STATIC_URL` settings are + required to end with a trailing slash to ensure there is a consistent + way to combine paths in templates. - * The UK-prefixed objects of ``django.contrib.localflavor.uk`` will only - 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. +1.6 +--- - * The :setting:`IGNORABLE_404_STARTS` and :setting:`IGNORABLE_404_ENDS` - settings have been superseded by :setting:`IGNORABLE_404_URLS` in - the 1.4 release. They will be removed. + * The compatibility modules ``django.utils.copycompat`` and + ``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 :doc:`form wizard ` has been - refactored to use class based views with pluggable backends in 1.4. - The previous implementation will be deprecated. + * The :func:`~django.views.decorators.csrf.csrf_response_exempt` and + :func:`~django.views.decorators.csrf.csrf_view_exempt` decorators will + 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 - :func:`~django.views.decorators.cache.cache_page` will be removed. + * The :class:`~django.core.cache.backends.memcached.CacheClass` backend + 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 - filter to the ``'mail_admins'`` logging handler will be removed. The - :setting:`LOGGING` setting should include this filter explicitly if - it is desired. + * The UK-prefixed objects of ``django.contrib.localflavor.uk`` will only + 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 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 :setting:`IGNORABLE_404_STARTS` and :setting:`IGNORABLE_404_ENDS` + settings have been superseded by :setting:`IGNORABLE_404_URLS` in + the 1.4 release. They will be removed. - * 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. + * The :doc:`form wizard ` has been + refactored to use class based views with pluggable backends in 1.4. + The previous implementation will be deprecated. - * 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. + * Legacy ways of calling + :func:`~django.views.decorators.cache.cache_page` will be removed. + + * The backward-compatibility shim to automatically add a debug-false + filter to the ``'mail_admins'`` logging handler will be removed. The + :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. diff --git a/docs/internals/release-process.txt b/docs/internals/release-process.txt index 2a56f0be92..47fff21025 100644 --- a/docs/internals/release-process.txt +++ b/docs/internals/release-process.txt @@ -7,30 +7,30 @@ Django's release process 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``. * ``A`` is the *major version* number, which is only incremented for major changes to Django, and these changes are not necessarily - backwards-compatible. That is, code you wrote for Django 6.0 may break - when we release Django 7.0. + backwards-compatible. That is, code you wrote for Django 1.2 may break + when we release Django 2.0. * ``B`` is the *minor version* number, which is incremented for large yet - backwards compatible changes. Code written for Django 6.4 will continue - to work under Django 6.5. + backwards compatible changes. Code written for Django 1.2 will continue + 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 - security fixes. A new micro-release will always be 100% - backwards-compatible with the previous micro-release. + * ``C`` is the *micro version* number, which is incremented for bug and + security fixes. A new micro-release will be 100% backwards-compatible with + 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. These are of the form ``A.B alpha/beta/rc N``, which means the ``Nth`` 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 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 @@ -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 between minor releases, and probably more often as needed. -These releases will always be 100% compatible with the associated minor release --- the answer to "should I upgrade to the latest micro release?" will always be -"yes." +These releases will be 100% compatible with the associated minor release, unless +this is impossible for security reasons. So the answer to "should I upgrade to +the latest micro release?" will always be "yes." 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 @@ -93,8 +93,20 @@ varying levels: * The current development trunk will get new features and bug fixes requiring major refactoring. - * All bug fixes applied to the trunk will also be applied to the last - minor release, to be released as the next micro release. + * Patches applied to the trunk will also be applied to the last minor + 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 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. - * Bug fixes will be applied to a ``1.3.X`` branch, and released as 1.3.1, - 1.3.2, etc. + * Critical bug fixes will be applied to a ``1.3.X`` branch, and released as + 1.3.1, 1.3.2, etc. - * Security releases 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.1``, etc. + * Security fixes will be applied to trunk, a ``1.3.X`` branch and a + ``1.2.X`` branch. They will trigger the release of ``1.3.1``, ``1.2.1``, + etc. .. _release-process: @@ -119,11 +131,11 @@ Release process 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. -After each previous release (and after a suitable cooling-off period of a week -or two), the core development team will examine the landscape and announce a -timeline for the next release. Most releases will be scheduled in the 6-9 month -range, but if we have bigger features to development we might schedule a longer -period to allow for more ambitious work. +After each release, and after a suitable cooling-off period of a few weeks, the +core development team will examine the landscape and announce a timeline for the +next release. Most releases will be scheduled in the 6-9 month range, but if we +have bigger features to development we might schedule a longer period to allow +for more ambitious work. Release cycle ------------- @@ -174,10 +186,11 @@ and an rc complete with string freeze two weeks before the end of the schedule. 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 -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 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 @@ -194,9 +207,9 @@ development will be happening in a bunch of places: * On trunk, development towards 1.2 proceeds with small additions, bugs fixes, etc. being checked in daily. - * On the branch "branches/releases/1.1.X", bug fixes found in the 1.1 - release are checked in as needed. At some point, this branch will be - released as "1.1.1", "1.1.2", etc. + * On the branch "branches/releases/1.1.X", fixes for critical bugs found in + the 1.1 release are checked in as needed. At some point, this branch will + be released as "1.1.1", "1.1.2", etc. * On the branch "branches/releases/1.0.X", security fixes are made if needed and released as "1.0.2", "1.0.3", etc.