Some heavy refactoring to the 1.2 release notes.

Don't bury the lede, folks!

git-svn-id: http://code.djangoproject.com/svn/django/trunk@13271 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/releases/1.2.txt

@@ -4,35 +4,372 @@
 Django 1.2 release notes
 ========================
 
-
-May 14, 2010
+*May 17, 2010.*
 
 Welcome to Django 1.2!
 
-Nearly a year in the making, Django 1.2 packs an impressive list of
-`new features`_, and lots of bugfixes. These release notes cover the
-new features, as well as important changes you'll want to be aware of
-when upgrading from Django 1.1 or older versions.
+Nearly a year in the making, Django 1.2 packs an impressive list of `new
+features`_ and lots of bug fixes. These release notes cover the new features,
+as well as important changes you'll want to be aware of when upgrading from
+Django 1.1 or older versions.
 
 .. _new features: `What's new in Django 1.2`_
 
+Overview
+========
+
+Django 1.2 introduces several large, important new features, including:
+
+    * Support for `multiple database connections`_ in a single Django instance.
+    
+    * `Model validation`_ inspired by Django's form validation.
+    
+    * Vastly `improved protection against Cross-Site Request Forgery`_ (CSRF).
+    
+    * A new `user "messages" framework`_ with support for cookie- and session-based
+      message for both anonymous and authenticated users.
+
+    * Hooks for `object-level permissions`_, `permissions for anonymous users`_,
+      and `more flexible username requirements`_.
+
+    * Customization of e-mail sending via `e-mail backends`_.
+
+    * New :ref:`"smart" if template tag <new-in-1.2-smart-if>` which supports
+      comparison operators.
+
+.. _multiple database connections: `support for multiple databases`_
+.. _improved protection against Cross-Site Request Forgery: `improved CSRF protection`_
+.. _user "messages" framework: `messages framework`_
+.. _more flexible username requirements: `relaxed requirements for usernames`_
+
+These are just the highlights; full details and a complete list of features `may
+be found below`_.
+
+.. _may be found below: `what's new in django 1.2`
+
+.. seealso::
+
+    `Django Advent`_ covered the release of Django 1.2 with a series of 
+    articles and tutorials that cover some of the new features in depth.
+        
+.. _django advent: http://djangoadvent.com/
+
+Wherever possible these features have been introduced in a backwards-compatible
+manner per :ref:`our API stability policy <misc-api-stability>` policy.
+
+However, a handful of features *have* changed in ways that, for some users, will be
+backwards-incompatible. The big changes are:
+
+    * The new CSRF protection framework is not backwards-compatible with
+      the old system. Users of the old system will not be affected until
+      the old system is removed in Django 1.4
+      
+      However, upgrading to the new CSRF protection framework requires a few
+      important backwards-incompatible changes, detailed in `CSRF Protection`_,
+      below.
+
+    * Authors of custom :class:`~django.db.models.Field` subclasses should be
+      aware that a number of methods have had a change in prototype, detailed
+      under `get_db_prep_*() methods on Field`_, below.
+      
+    * The internals of template tags have changed somewhat; authors of custom
+      template tags that need to store state (e.g. custom control flow tags)
+      should ensure that their code follows the new rules for `stateful template
+      tags`_
+    
+    * The :func:`~django.contrib.auth.decorators.user_passes_test`,
+      :func:`~django.contrib.auth.decorators.login_required`, and
+      :func:`~django.contrib.auth.decorators.permission_required`, decorators
+      from :mod:`django.contrib.auth` only apply to functions and no longer
+      work on methods. There's a simple one-line fix `detailed below`_.
+
+.. _detailed below: `user_passes_test, login_required and permission_required`_
+
+Again, these are just the big features that will affect the most users. Users
+upgrading from previous versions of Django are heavily encouraged to consult
+the complete list of :ref:`backwards-incompatible changes
+<backwards-incompatible-changes-1.2>` and the list of :ref:`deprecated
+features <deprecated-features-1.2>`.
+
+What's new in Django 1.2
+========================
+
+Support for multiple databases
+------------------------------
+
+Django 1.2 adds the ability to use :ref:`more than one database
+<topics-db-multi-db>` in your Django project. Queries can be issued at a
+specific database with the `using()` method on ``QuerySet`` objects. Individual
+objects can be saved to a specific database by providing a ``using`` argument
+when you call ``save()``.
+
+Model validation
+----------------
+
+Model instances now have support for :ref:`validating their own data
+<validating-objects>`, and both model and form fields now accept configurable
+lists of :ref:`validators <ref-validators>` specifying reusable, encapsulated
+validation behavior. Note, however, that validation must still be performed
+explicitly. Simply invoking a model instance's ``save()`` method will not
+perform any validation of the instance's data.
+
+Improved CSRF protection
+------------------------
+
+Django now has much improved protection against :ref:`Cross-Site Request Forgery
+(CSRF) attacks<ref-contrib-csrf>`. This type of attack occurs when a malicious
+Web site contains a link, a form button or some JavaScript that is intended to
+perform some action on your Web site, using the credentials of a logged-in user
+who visits the malicious site in their browser. A related type of attack, "login
+CSRF," where an attacking site tricks a user's browser into logging into a site
+with someone else's credentials, is also covered.
+
+Messages framework
+------------------
+
+Django now includes a robust and configurable :ref:`messages framework
+<ref-contrib-messages>` with built-in support for cookie- and session-based
+messaging, for both anonymous and authenticated clients. The messages framework
+replaces the deprecated user message API and allows you to temporarily store
+messages in one request and retrieve them for display in a subsequent request
+(usually the next one).
+
+Object-level permissions
+------------------------
+
+A foundation for specifying permissions at the per-object level has been added.
+Although there is no implementation of this in core, a custom authentication
+backend can provide this implementation and it will be used by
+:class:`django.contrib.auth.models.User`. See the :ref:`authentication docs
+<topics-auth>` for more information.
+
+Permissions for anonymous users
+-------------------------------
+
+If you provide a custom auth backend with ``supports_anonymous_user`` set to
+``True``, AnonymousUser will check the backend for permissions, just like
+User already did.  This is useful for centralizing permission handling - apps
+can always delegate the question of whether something is allowed or not to
+the authorization/authentication backend. See the :ref:`authentication
+docs <topics-auth>` for more details.
+
+Relaxed requirements for usernames
+----------------------------------
+
+The built-in :class:`~django.contrib.auth.models.User` model's
+:attr:`~django.contrib.auth.models.User.username` field now allows a wider range
+of characters, including ``@``, ``+``, ``.`` and ``-`` characters.
+
+E-mail backends
+---------------
+
+You can now :ref:`configure the way that Django sends e-mail
+<topic-email-backends>`. Instead of using SMTP to send all e-mail, you
+can now choose a configurable e-mail backend to send messages. If your
+hosting provider uses a sandbox or some other non-SMTP technique for
+sending mail, you can now construct an e-mail backend that will allow
+Django's standard :ref:`mail sending methods<topics-email>` to use
+those facilities.
+
+This also makes it easier to debug mail sending. Django ships with
+backend implementations that allow you to send e-mail to a
+:ref:`file<topic-email-file-backend>`, to the
+:ref:`console<topic-email-console-backend>`, or to
+:ref:`memory<topic-email-memory-backend>`. You can even configure all
+e-mail to be :ref:`thrown away<topic-email-dummy-backend>`.
+
+.. _new-in-1.2-smart-if:
+
+"Smart" :ttag:`if` tag
+----------------------
+
+The :ttag:`if` tag has been upgraded to be much more powerful. First, we've
+added support for comparison operators. No longer will you have to type:
+
+.. code-block:: html+django
+
+    {% ifnotequal a b %}
+     ...
+    {% endifnotequal %}
+
+You can now do this:
+
+.. code-block:: html+django
+
+    {% if a != b %}
+     ...
+    {% endif %}
+
+There's really no reason to use ``{% ifequal %}`` or ``{% ifnotequal %}``
+anymore, unless you're the nostalgic type.
+
+The operators supported are ``==``, ``!=``, ``<``, ``>``, ``<=``, ``>=``,
+``in`` and ``not in``, all of which work like the Python operators, in addition
+to ``and``, ``or`` and ``not``, which were already supported.
+
+Also, filters may now be used in the ``if`` expression. For example:
+
+.. code-block:: html+django
+
+      <div
+        {% if user.email|lower == message.recipient|lower %}
+          class="highlight"
+        {% endif %}
+      >{{ message }}</div>
+
+Template caching
+----------------
+
+In previous versions of Django, every time you rendered a template, it
+would be reloaded from disk. In Django 1.2, you can use a :ref:`cached
+template loader <template-loaders>` to load templates once, then
+cache the result for every subsequent render. This can lead to a
+significant performance improvement if your templates are broken into
+lots of smaller subtemplates (using the ``{% extends %}`` or ``{%
+include %}`` tags).
+
+As a side effect, it is now much easier to support non-Django template
+languages. For more details, see the :ref:`notes on supporting
+non-Django template languages<topic-template-alternate-language>`.
+
+Natural keys in fixtures
+------------------------
+
+Fixtures can now refer to remote objects using
+:ref:`topics-serialization-natural-keys`. This lookup scheme is an
+alternative to the normal primary-key based object references in a
+fixture, improving readability and resolving problems referring to
+objects whose primary key value may not be predictable or known.
+
+Fast failure for tests
+----------------------
+
+Both the :djadmin:`test` subcommand of ``django-admin.py`` and the
+``runtests.py`` script used to run Django's own test suite now support a
+``--failfast`` option. When specified, this option causes the test runner to
+exit after encountering a failure instead of continuing with the test run. In
+addition, the handling of ``Ctrl-C`` during a test run has been improved to
+trigger a graceful exit from the test run that reports details of the tests that
+were run before the interruption.
+
+``BigIntegerField``
+-------------------
+
+Models can now use a 64-bit :class:`~django.db.models.BigIntegerField` type.
+
+Improved localization
+---------------------
+
+Django's :ref:`internationalization framework <topics-i18n>` has been expanded
+with locale-aware formatting and form processing. That means, if enabled, dates
+and numbers on templates will be displayed using the format specified for the
+current locale. Django will also use localized formats when parsing data in
+forms. See :ref:`Format localization <format-localization>` for more details.
+
+``readonly_fields`` in ``ModelAdmin``
+-------------------------------------
+
+:attr:`django.contrib.admin.ModelAdmin.readonly_fields` has been added to
+enable non-editable fields in add/change pages for models and inlines. Field
+and calculated values can be displayed alongside editable fields.
+
+Customizable syntax highlighting
+--------------------------------
+
+You can now use a ``DJANGO_COLORS`` environment variable to modify or disable
+the colors used by ``django-admin.py`` to provide :ref:`syntax highlighting
+<syntax-coloring>`.
+
+Syndication feeds as views
+--------------------------
+
+:ref:`Syndication feeds <ref-contrib-syndication>` can now be used directly as
+views in your :ref:`URLconf <topics-http-urls>`. This means that you can
+maintain complete control over the URL structure of your feeds. Like any other
+view, feeds views are passed a ``request`` object, so you can do anything you
+would normally do with a view, like user based access control, or making a feed
+a named URL.
+
+GeoDjango
+---------
+
+The most significant new feature for ref:`GeoDjango <ref-contrib-gis>`
+in 1.2 is support for multiple spatial databases.  As a result,
+the following :ref:`spatial database backends <spatial-backends>`
+are now included:
+
+* :mod:`django.contrib.gis.db.backends.postgis`
+* :mod:`django.contrib.gis.db.backends.mysql`
+* :mod:`django.contrib.gis.db.backends.oracle`
+* :mod:`django.contrib.gis.db.backends.spatialite`
+
+GeoDjango now supports the rich capabilities added
+in the `PostGIS 1.5 release <http://postgis.refractions.net/documentation/manual-1.5/>`_.
+New features include suppport for the the :ref:`geography type <geography-type>`
+and enabling of :ref:`distance queries <distance-queries>`
+with non-point geometries on geographic coordinate systems.
+
+Support for 3D geometry fields was added, and may be enabled
+by setting the :attr:`~django.contrib.gis.db.models.GeometryField.dim`
+keyword to 3 in your :class:`~django.contrib.gis.db.models.GeometryField`.
+The :class:`~django.contrib.gis.db.models.Extent3D` aggregate
+and :meth:`~django.contrib.gis.db.models.GeoQuerySet.extent3d` ``GeoQuerySet``
+method were added as a part of this feature.
+
+The following :class:`~django.contrib.gis.db.models.GeoQeurySet`
+methods are new in 1.2:
+
+* :meth:`~django.contrib.gis.db.models.GeoQuerySet.force_rhr`
+* :meth:`~django.contrib.gis.db.models.GeoQuerySet.reverse_geom`
+* :meth:`~django.contrib.gis.db.models.GeoQuerySet.geohash`
+
+The :ref:`GEOS interface <ref-geos>` was updated to use
+thread-safe C library functions when available on the platform.
+
+The :ref:`GDAL interface <ref-gdal>` now allows the user to
+set a :attr:`~django.contrib.gis.gdal.Layer.spatial_filter` on
+the features returned when iterating over a
+:class:`~django.contrib.gis.gdal.Layer`.
+
+Finally, :ref:`GeoDjango's documentation <ref-contrib-gis>` is now
+included with Django's and is no longer
+hosted separately at `geodjango.org <http://geodjango.org/>`_.
+
+.. _1.2-js-assisted-inlines:
+
+JavaScript-assisted handling of inline related objects in the admin
+-------------------------------------------------------------------
+
+If a user has JavaScript enabled in their browser, the interface for
+inline objects in the admin now allows inline objects to be
+dynamically added and removed. Users without JavaScript-enabled
+browsers will see no change in the behavior of inline objects.
+
+New ``now`` template tag format specifier characters: ``c`` and ``u``
+---------------------------------------------------------------------
+
+The argument to the :ttag:`now` has gained two new format characters:
+``c`` to specify that a datetime value should be formatted in ISO 8601
+format, and ``u`` that allows output of the microseconds part of a
+datetime or time value.
+
+These are also available in others parts like the :tfilter:`date` and
+:tfilter:`time` template filters, the ``humanize`` template tag library
+and the new `format localization`_ framework.
+
+.. _format localization: `Improved localization`_
+
 .. _backwards-incompatible-changes-1.2:
 
 Backwards-incompatible changes in 1.2
 =====================================
 
-There are a number of changes in Django 1.2 which will be
-backwards-incompatible; per :ref:`our API stability policy
-<misc-api-stability>`, most such changes are being introduced
-gradually to allow adequate time to upgrade existing code. For most of
-the changes listed below, code written for Django 1.1 or older will
-simply raise a ``PendingDeprecationWarning`` in Django 1.2, followed
-by a ``DeprecationWarning`` in Django 1.3 before such code finally
-stops working entirely in Django 1.4.
+Wherever possible the new features above have been introduced in a
+backwards-compatible manner per :ref:`our API stability policy
+<misc-api-stability>` policy.
 
-Do note, however, that some of the items listed below may require
-immediate changes; we encourage you to read these notes carefully to
-determine how they'll impact your code.
+However, a handful of features *have* changed in ways that, for some users, will be
+backwards-incompatible. Those changes are detailed below.
 
 CSRF Protection
 ---------------
@@ -59,119 +396,6 @@ should be aware of:
    compatible imports in the old locations, which are deprecated and
    will cease to be supported in Django 1.4).
 
-:ttag:`if` tag changes
-----------------------
-
-Due to new features in the :ttag:`if` template tag, it no longer
-accepts 'and', 'or' and 'not' as valid **variable** names. Previously,
-these strings could be used as variable names. Now, the keyword status
-is always enforced, and template code such as ``{% if not %}`` or ``{%
-if and %}`` will throw a ``TemplateSyntaxError``. Also, ``in`` is a
-new keyword and so is not a valid variable name in this tag.
-
-``LazyObject``
---------------
-
-``LazyObject`` is an undocumented utility class used for lazily
-wrapping other objects of unknown type. In Django 1.1 and earlier, it
-handled introspection in a non-standard way, depending on wrapped
-objects implementing a public method named
-``get_all_members()``. Since this could easily lead to name clashes,
-it has been changed to use the standard Python introspection method,
-involving ``__members__`` and ``__dir__()``.  If you used
-``LazyObject`` in your own code and implemented the
-``get_all_members()`` method for wrapped objects, you need to make the
-following changes:
-
- * If your class does not have special requirements for introspection (i.e., you
-   have not implemented ``__getattr__()`` or other methods that allow for
-   attributes not discoverable by normal mechanisms), you can simply remove the
-   ``get_all_members()`` method. The default implementation on ``LazyObject``
-   will do the right thing.
-
- * If you have more complex requirements for introspection, first
-   rename the ``get_all_members()`` method to ``__dir__()``. This is
-   the standard method, from Python 2.6 onwards, for supporting
-   introspection. If you require support for Python versions earlier
-   than 2.6, add the following code to the class::
-
-       __members__ = property(lambda self: self.__dir__())
-
-.. _specifying-databases:
-
-Specifying databases
---------------------
-
-Prior to Django 1.2, Django used a number of settings to control
-access to a single database. Django 1.2 introduces support for
-multiple databases, and as a result the way you define database
-settings has changed.
-
-Any existing Django settings file will continue to work as expected
-until Django 1.4. Until then, old-style database settings will be
-automatically translated to the new-style format.
-
-In the old-style (pre 1.2) format, you had a number of ``DATABASE_``
-settings in your settings file. For example::
-
-    DATABASE_NAME = 'test_db'
-    DATABASE_ENGINE = 'postgresql_psycopg2'
-    DATABASE_USER = 'myusername'
-    DATABASE_PASSWORD = 's3krit'
-
-These settings are now in a dictionary named
-:setting:`DATABASES`. Each item in the dictionary corresponds to a
-single database connection, with the name ``'default'`` describing the
-default database connection. The setting names have also been
-shortened. The previous sample settings would now look like this::
-
-    DATABASES = {
-        'default': {
-            'NAME': 'test_db',
-            'ENGINE': 'django.db.backends.postgresql_psycopg2',
-            'USER': 'myusername',
-            'PASSWORD': 's3krit',
-        }
-    }
-
-This affects the following settings:
-
-    =========================================  ==========================
-     Old setting                                New Setting
-    =========================================  ==========================
-    :setting:`DATABASE_ENGINE`                 :setting:`ENGINE`
-    :setting:`DATABASE_HOST`                   :setting:`HOST`
-    :setting:`DATABASE_NAME`                   :setting:`NAME`
-    :setting:`DATABASE_OPTIONS`                :setting:`OPTIONS`
-    :setting:`DATABASE_PASSWORD`               :setting:`PASSWORD`
-    :setting:`DATABASE_PORT`                   :setting:`PORT`
-    :setting:`DATABASE_USER`                   :setting:`USER`
-    :setting:`TEST_DATABASE_CHARSET`           :setting:`TEST_CHARSET`
-    :setting:`TEST_DATABASE_COLLATION`         :setting:`TEST_COLLATION`
-    :setting:`TEST_DATABASE_NAME`              :setting:`TEST_NAME`
-    =========================================  ==========================
-
-These changes are also required if you have manually created a database
-connection using ``DatabaseWrapper()`` from your database backend of choice.
-
-In addition to the change in structure, Django 1.2 removes the special
-handling for the built-in database backends. All database backends
-must now be specified by a fully qualified module name (i.e.,
-``django.db.backends.postgresql_psycopg2``, rather than just
-``postgresql_psycopg2``).
-
-``__dict__`` on model instances
--------------------------------
-
-Historically, the ``__dict__`` attribute of a model instance has only contained
-attributes corresponding to the fields on a model.
-
-In order to support multiple database configurations, Django 1.2 has
-added a ``_state`` attribute to object instances. This attribute will
-appear in ``__dict__`` for a model instance. If your code relies on
-iterating over ``__dict__`` to obtain a list of fields, you must now
-be prepared to handle or filter out the ``_state`` attribute.
-
 ``get_db_prep_*()`` methods on ``Field``
 ----------------------------------------
 
@@ -282,27 +506,6 @@ the state of the :ttag:`cycle` tag would leak between multiple
 renderings of the same :ttag:`include`. Now that the :ttag:`cycle` tag
 is thread safe, this leakage no longer occurs.
 
-Test runner exit status code
-----------------------------
-
-The exit status code of the test runners (``tests/runtests.py`` and ``python
-manage.py test``) no longer represents the number of failed tests, because a
-failure of 256 or more tests resulted in a wrong exit status code. The exit
-status code for the test runner is now 0 for success (no failing tests) and 1
-for any number of test failures. If needed, the number of test failures can be
-found at the end of the test runner's output.
-
-Cookie encoding
----------------
-
-To fix bugs with cookies in Internet Explorer, Safari, and possibly
-other browsers, our encoding of cookie values was changed so that the
-comma and semicolon are treated as non-safe characters, and are
-therefore encoded as ``\054`` and ``\073`` respectively.  This could
-produce backwards incompatibilities, especially if you are storing
-comma or semi-colon in cookies and have javascript code that parses
-and manipulates cookie values client-side.
-
 ``user_passes_test``, ``login_required`` and ``permission_required``
 --------------------------------------------------------------------
 
@@ -355,6 +558,78 @@ change also applies to other decorators introduced since 1.1,
 including ``csrf_protect``, ``cache_control`` and anything created
 using ``decorator_from_middleware``.
 
+:ttag:`if` tag changes
+----------------------
+
+Due to new features in the :ttag:`if` template tag, it no longer
+accepts 'and', 'or' and 'not' as valid **variable** names. Previously,
+these strings could be used as variable names. Now, the keyword status
+is always enforced, and template code such as ``{% if not %}`` or ``{%
+if and %}`` will throw a ``TemplateSyntaxError``. Also, ``in`` is a
+new keyword and so is not a valid variable name in this tag.
+
+``LazyObject``
+--------------
+
+``LazyObject`` is an undocumented-but-often-used utility class used for lazily
+wrapping other objects of unknown type. 
+
+In Django 1.1 and earlier, it handled introspection in a non-standard way,
+depending on wrapped objects implementing a public method named
+``get_all_members()``. Since this could easily lead to name clashes, it has been
+changed to use the standard Python introspection method, involving
+``__members__`` and ``__dir__()``. 
+
+If you used ``LazyObject`` in your own code
+and implemented the ``get_all_members()`` method for wrapped objects, you'll need
+to make a couple of changes:
+
+First, if your class does not have special requirements for introspection (i.e.,
+you have not implemented ``__getattr__()`` or other methods that allow for
+attributes not discoverable by normal mechanisms), you can simply remove the
+``get_all_members()`` method. The default implementation on ``LazyObject`` will
+do the right thing.
+
+If you have more complex requirements for introspection, first rename the
+``get_all_members()`` method to ``__dir__()``. This is the standard
+introspection method for Python 2.6 and above. If you require support for Python
+versions earlier than 2.6, add the following code to the class::
+
+    __members__ = property(lambda self: self.__dir__())
+
+``__dict__`` on model instances
+-------------------------------
+
+Historically, the ``__dict__`` attribute of a model instance has only contained
+attributes corresponding to the fields on a model.
+
+In order to support multiple database configurations, Django 1.2 has
+added a ``_state`` attribute to object instances. This attribute will
+appear in ``__dict__`` for a model instance. If your code relies on
+iterating over ``__dict__`` to obtain a list of fields, you must now
+be prepared to handle or filter out the ``_state`` attribute.
+
+Test runner exit status code
+----------------------------
+
+The exit status code of the test runners (``tests/runtests.py`` and ``python
+manage.py test``) no longer represents the number of failed tests, because a
+failure of 256 or more tests resulted in a wrong exit status code. The exit
+status code for the test runner is now 0 for success (no failing tests) and 1
+for any number of test failures. If needed, the number of test failures can be
+found at the end of the test runner's output.
+
+Cookie encoding
+---------------
+
+To fix bugs with cookies in Internet Explorer, Safari, and possibly
+other browsers, our encoding of cookie values was changed so that the
+comma and semicolon are treated as non-safe characters, and are
+therefore encoded as ``\054`` and ``\073`` respectively.  This could
+produce backwards incompatibilities, especially if you are storing
+comma or semi-colon in cookies and have javascript code that parses
+and manipulates cookie values client-side.
+
 ``ModelForm.is_valid()`` and ``ModelForm.errors``
 -------------------------------------------------
 
@@ -407,12 +682,95 @@ will need to update your FormSet and/or admin definitions.
 
 .. seealso::
 
-    :ref:`1.2-js-assisted-inlines`
+    :ref:`1.2-js-assisted-inlines`
+
+.. _deprecated-features-1.2:
+
+Features deprecated in 1.2
+==========================
+
+Finally, Django 1.2 deprecates some features from earlier releases.
+These features are still supported, but will be gradually phased out
+over the next few release cycles.
+
+Code take advantage of any of the features below will raise a
+``PendingDeprecationWarning`` in Django 1.2. This warning will be silent by
+default, but may be turned on using Python's `warnings module`_, or by running
+Python with a ``-Wd`` or `-Wall` flag.
+
+.. _warnings module: http://docs.python.org/library/warnings.html
+
+In Django 1.3, these warnings will become a ``DeprecationWarning``, which is *not* silent. In Django 1.4
+support for these features will be removed entirely. 
+
+.. seealso::
+
+    For more details, see the documentation :ref:`Django's release process
+    <internals-release-process>` and our :ref:`deprecation timeline
+    <internals-deprecation>`.`
+
+.. _specifying-databases:
+
+Specifying databases
+--------------------
+
+Prior to Django 1.2, Django used a number of settings to control
+access to a single database. Django 1.2 introduces support for
+multiple databases, and as a result the way you define database
+settings has changed.
+
+Any existing Django settings file will continue to work as expected
+until Django 1.4. Until then, old-style database settings will be
+automatically translated to the new-style format.
+
+In the old-style (pre 1.2) format, you had a number of ``DATABASE_``
+settings in your settings file. For example::
+
+    DATABASE_NAME = 'test_db'
+    DATABASE_ENGINE = 'postgresql_psycopg2'
+    DATABASE_USER = 'myusername'
+    DATABASE_PASSWORD = 's3krit'
+
+These settings are now in a dictionary named
+:setting:`DATABASES`. Each item in the dictionary corresponds to a
+single database connection, with the name ``'default'`` describing the
+default database connection. The setting names have also been
+shortened. The previous sample settings would now look like this::
+
+    DATABASES = {
+        'default': {
+            'NAME': 'test_db',
+            'ENGINE': 'django.db.backends.postgresql_psycopg2',
+            'USER': 'myusername',
+            'PASSWORD': 's3krit',
+        }
+    }
+
+This affects the following settings:
+
+    =========================================  ==========================
+     Old setting                                New Setting
+    =========================================  ==========================
+    :setting:`DATABASE_ENGINE`                 :setting:`ENGINE`
+    :setting:`DATABASE_HOST`                   :setting:`HOST`
+    :setting:`DATABASE_NAME`                   :setting:`NAME`
+    :setting:`DATABASE_OPTIONS`                :setting:`OPTIONS`
+    :setting:`DATABASE_PASSWORD`               :setting:`PASSWORD`
+    :setting:`DATABASE_PORT`                   :setting:`PORT`
+    :setting:`DATABASE_USER`                   :setting:`USER`
+    :setting:`TEST_DATABASE_CHARSET`           :setting:`TEST_CHARSET`
+    :setting:`TEST_DATABASE_COLLATION`         :setting:`TEST_COLLATION`
+    :setting:`TEST_DATABASE_NAME`              :setting:`TEST_NAME`
+    =========================================  ==========================
 
-.. _deprecated-features-1.2:
+These changes are also required if you have manually created a database
+connection using ``DatabaseWrapper()`` from your database backend of choice.
 
-Features deprecated in 1.2
-==========================
+In addition to the change in structure, Django 1.2 removes the special
+handling for the built-in database backends. All database backends
+must now be specified by a fully qualified module name (i.e.,
+``django.db.backends.postgresql_psycopg2``, rather than just
+``postgresql_psycopg2``).
 
 ``postgresql`` database backend
 -------------------------------
@@ -543,12 +901,12 @@ The same applies to the globals found in ``django.forms.fields``:
 
 Use ``django.utils.formats.get_format()`` to get the appropriate formats.
 
-email_re
---------
+``email_re``
+------------
 
-An undocumented regex for validating email addresses has been moved from
-django.form.fields to django.core.validators. You will need to update
-your imports if you are using it.
+An undocumented regular expression for validating email addresses has been moved
+from ``django.form.fields`` to ``django.core.validators``. You will need to
+update your imports if you are using it.
 
 Function-based test runners
 ---------------------------
@@ -744,270 +1102,3 @@ Language code ``no``
 The currently used language code for Norwegian Bokmål ``no`` is being
 replaced by the more common language code ``nb``.
 
-What's new in Django 1.2
-========================
-
-Improved CSRF protection
-------------------------
-
-Django now has much improved protection against :ref:`Cross-Site
-Request Forgery (CSRF) attacks<ref-contrib-csrf>`. This type of attack
-occurs when a malicious Web site contains a link, a form button or
-some JavaScript that is intended to perform some action on your Web
-site, using the credentials of a logged-in user who visits the
-malicious site in their browser. A related type of attack, "login
-CSRF," where an attacking site tricks a user's browser into logging
-into a site with someone else's credentials, is also covered.
-
-E-mail backends
----------------
-
-You can now :ref:`configure the way that Django sends e-mail
-<topic-email-backends>`. Instead of using SMTP to send all e-mail, you
-can now choose a configurable e-mail backend to send messages. If your
-hosting provider uses a sandbox or some other non-SMTP technique for
-sending mail, you can now construct an e-mail backend that will allow
-Django's standard :ref:`mail sending methods<topics-email>` to use
-those facilities.
-
-This also makes it easier to debug mail sending. Django ships with
-backend implementations that allow you to send e-mail to a
-:ref:`file<topic-email-file-backend>`, to the
-:ref:`console<topic-email-console-backend>`, or to
-:ref:`memory<topic-email-memory-backend>`. You can even configure all
-e-mail to be :ref:`thrown away<topic-email-dummy-backend>`.
-
-Messages framework
-------------------
-
-Django now includes a robust and configurable :ref:`messages framework
-<ref-contrib-messages>` with built-in support for cookie- and session-based
-messaging, for both anonymous and authenticated clients. The messages framework
-replaces the deprecated user message API and allows you to temporarily store
-messages in one request and retrieve them for display in a subsequent request
-(usually the next one).
-
-Support for multiple databases
-------------------------------
-
-Django 1.2 adds the ability to use :ref:`more than one database
-<topics-db-multi-db>` in your Django project. Queries can be
-issued at a specific database with the `using()` method on
-``QuerySet`` objects. Individual objects can be saved to a specific database
-by providing a ``using`` argument when you call ``save()``.
-
-"Smart" :ttag:`if` tag
-----------------------
-
-The :ttag:`if` tag has been upgraded to be much more powerful. First, we've
-added support for comparison operators. No longer will you have to type:
-
-.. code-block:: html+django
-
-    {% ifnotequal a b %}
-     ...
-    {% endifnotequal %}
-
-You can now do this:
-
-.. code-block:: html+django
-
-    {% if a != b %}
-     ...
-    {% endif %}
-
-There's really no reason to use ``{% ifequal %}`` or ``{% ifnotequal %}``
-anymore, unless you're the nostalgic type.
-
-The operators supported are ``==``, ``!=``, ``<``, ``>``, ``<=``, ``>=``,
-``in`` and ``not in``, all of which work like the Python operators, in addition
-to ``and``, ``or`` and ``not``, which were already supported.
-
-Also, filters may now be used in the ``if`` expression. For example:
-
-.. code-block:: html+django
-
-      <div
-        {% if user.email|lower == message.recipient|lower %}
-          class="highlight"
-        {% endif %}
-      >{{ message }}</div>
-
-Template caching
-----------------
-
-In previous versions of Django, every time you rendered a template, it
-would be reloaded from disk. In Django 1.2, you can use a :ref:`cached
-template loader <template-loaders>` to load templates once, then
-cache the result for every subsequent render. This can lead to a
-significant performance improvement if your templates are broken into
-lots of smaller subtemplates (using the ``{% extends %}`` or ``{%
-include %}`` tags).
-
-As a side effect, it is now much easier to support non-Django template
-languages. For more details, see the :ref:`notes on supporting
-non-Django template languages<topic-template-alternate-language>`.
-
-Natural keys in fixtures
-------------------------
-
-Fixtures can now refer to remote objects using
-:ref:`topics-serialization-natural-keys`. This lookup scheme is an
-alternative to the normal primary-key based object references in a
-fixture, improving readability and resolving problems referring to
-objects whose primary key value may not be predictable or known.
-
-``BigIntegerField``
--------------------
-
-Models can now use a 64-bit :class:`~django.db.models.BigIntegerField` type.
-
-Fast failure for tests
-----------------------
-
-Both the :djadmin:`test` subcommand of ``django-admin.py`` and the ``runtests.py``
-script used to run Django's own test suite now support a ``--failfast`` option.
-When specified, this option causes the test runner to exit after encountering
-a failure instead of continuing with the test run. In addition, the handling
-of ``Ctrl-C`` during a test run has been improved to trigger a graceful exit
-from the test run that reports details of the tests that were run before the
-interruption.
-
-Improved localization
----------------------
-
-Django's :ref:`internationalization framework <topics-i18n>` has been
-expanded with locale-aware formatting and form processing. That means, if
-enabled, dates and numbers on templates will be displayed using the format
-specified for the current locale. Django will also use localized formats
-when parsing data in forms. See
-:ref:`Format localization <format-localization>` for more details.
-
-``readonly_fields`` in ``ModelAdmin``
--------------------------------------
-
-:attr:`django.contrib.admin.ModelAdmin.readonly_fields` has been added to
-enable non-editable fields in add/change pages for models and inlines. Field
-and calculated values can be displayed alongside editable fields.
-
-Customizable syntax highlighting
---------------------------------
-
-You can now use a ``DJANGO_COLORS`` environment variable to modify
-or disable the colors used by ``django-admin.py`` to provide
-:ref:`syntax highlighting <syntax-coloring>`.
-
-Model validation
-----------------
-
-Model instances now have support for :ref:`validating their own data
-<validating-objects>`, and both model and form fields now accept
-configurable lists of :ref:`validators <ref-validators>` specifying
-reusable, encapsulated validation behavior. Note, however, that
-validation must still be performed explicitly. Simply invoking a model
-instance's ``save()`` method will not perform any validation of the
-instance's data.
-
-Object-level permissions
-------------------------
-
-A foundation for specifying permissions at the per-object level has been added.
-Although there is no implementation of this in core, a custom authentication
-backend can provide this implementation and it will be used by
-:class:`django.contrib.auth.models.User`. See the :ref:`authentication docs
-<topics-auth>` for more information.
-
-Permissions for anonymous users
--------------------------------
-
-If you provide a custom auth backend with ``supports_anonymous_user`` set to
-``True``, AnonymousUser will check the backend for permissions, just like
-User already did.  This is useful for centralizing permission handling - apps
-can always delegate the question of whether something is allowed or not to
-the authorization/authentication backend. See the :ref:`authentication
-docs <topics-auth>` for more details.
-
-Syndication feeds as views
---------------------------
-
-:ref:`Syndication feeds <ref-contrib-syndication>` can now be used directly as
-views in your :ref:`URLconf <topics-http-urls>`. This means that you can
-maintain complete control over the URL structure of your feeds. Like any other view, feeds views are passed a ``request`` object, so you can
-do anything you would normally do with a view, like user based access control,
-or making a feed a named URL.
-
-Relaxed requirements for usernames
-----------------------------------
-
-The built-in :class:`~django.contrib.auth.models.User` model's
-:attr:`~django.contrib.auth.models.User.username` field now allows a wider range
-of characters, including ``@``, ``+``, ``.`` and ``-`` characters.
-
-GeoDjango
----------
-
-The most significant new feature for ref:`GeoDjango <ref-contrib-gis>`
-in 1.2 is support for multiple spatial databases.  As a result,
-the following :ref:`spatial database backends <spatial-backends>`
-are now included:
-
-* :mod:`django.contrib.gis.db.backends.postgis`
-* :mod:`django.contrib.gis.db.backends.mysql`
-* :mod:`django.contrib.gis.db.backends.oracle`
-* :mod:`django.contrib.gis.db.backends.spatialite`
-
-GeoDjango now supports the rich capabilities added
-in the `PostGIS 1.5 release <http://postgis.refractions.net/documentation/manual-1.5/>`_.
-New features include suppport for the the :ref:`geography type <geography-type>`
-and enabling of :ref:`distance queries <distance-queries>`
-with non-point geometries on geographic coordinate systems.
-
-Support for 3D geometry fields was added, and may be enabled
-by setting the :attr:`~django.contrib.gis.db.models.GeometryField.dim`
-keyword to 3 in your :class:`~django.contrib.gis.db.models.GeometryField`.
-The :class:`~django.contrib.gis.db.models.Extent3D` aggregate
-and :meth:`~django.contrib.gis.db.models.GeoQuerySet.extent3d` ``GeoQuerySet``
-method were added as a part of this feature.
-
-The following :class:`~django.contrib.gis.db.models.GeoQeurySet`
-methods are new in 1.2:
-
-* :meth:`~django.contrib.gis.db.models.GeoQuerySet.force_rhr`
-* :meth:`~django.contrib.gis.db.models.GeoQuerySet.reverse_geom`
-* :meth:`~django.contrib.gis.db.models.GeoQuerySet.geohash`
-
-The :ref:`GEOS interface <ref-geos>` was updated to use
-thread-safe C library functions when available on the platform.
-
-The :ref:`GDAL interface <ref-gdal>` now allows the user to
-set a :attr:`~django.contrib.gis.gdal.Layer.spatial_filter` on
-the features returned when iterating over a
-:class:`~django.contrib.gis.gdal.Layer`.
-
-Finally, :ref:`GeoDjango's documentation <ref-contrib-gis>` is now
-included with Django's and is no longer
-hosted separately at `geodjango.org <http://geodjango.org/>`_.
-
-.. _1.2-js-assisted-inlines:
-
-JavaScript-assisted handling of inline related objects in the admin
--------------------------------------------------------------------
-
-If a user has JavaScript enabled in their browser, the interface for
-inline objects in the admin now allows inline objects to be
-dynamically added and removed. Users without JavaScript-enabled
-browsers will see no change in the behavior of inline objects.
-
-New ``now`` template tag format specifier characters: ``c`` and ``u``
----------------------------------------------------------------------
-
-The argument to the :ttag:`now` has gained two new format characters:
-``c`` to specify that a datetime value should be formatted in ISO 8601
-format, and ``u`` that allows output of the microseconds part of a
-datetime or time value.
-
-These are also available in others parts like the :tfilter:`date` and
-:tfilter:`time` template filters, the ``humanize`` template tag library
-and the new `format localization`_ framework.
-
-.. _format localization: `Improved localization`_