Added 1.5 beta release notes.

Backport of [7a62339f59] from master.

docs/releases/1.5-beta-1.txt

@@ -0,0 +1,702 @@
+=============================
+Django 1.5 beta release notes
+=============================
+
+November 27, 2012.
+
+Welcome to Django 1.5 beta!
+
+This is the second in a series of preview/development releases leading
+up to the eventual release of Django 1.5, scheduled for Decemeber
+2012. This release is primarily targeted at developers who are
+interested in trying out new features and testing the Django codebase
+to help identify and resolve bugs prior to the final 1.5 release.
+
+As such, this release is *not* intended for production use, and any such use
+is discouraged.
+
+These release notes cover the `new features`_, as well
+as some `backwards incompatible changes`_ you'll want to be aware of
+when upgrading from Django 1.4 or older versions. We've also dropped some
+features, which are detailed in :doc:`our deprecation plan
+</internals/deprecation>`, and we've `begun the deprecation process for some
+features`_.
+
+.. _`new features`: `What's new in Django 1.5`_
+.. _`backwards incompatible changes`: `Backwards incompatible changes in 1.5`_
+.. _`begun the deprecation process for some features`: `Features deprecated in 1.5`_
+
+Overview
+========
+
+The biggest new feature in Django 1.5 is the `configurable User model`_. Before
+Django 1.5, applications that wanted to use Django's auth framework
+(:mod:`django.contrib.auth`) were forced to use Django's definition of a "user".
+In Django 1.5, you can now swap out the ``User`` model for one that you write
+yourself. This could be a simple extension to the existing ``User`` model -- for
+example, you could add a Twitter or Facebook ID field -- or you could completely
+replace the ``User`` with one totally customized for your site.
+
+Django 1.5 is also the first release with `Python 3 support`_! We're labeling
+this support "experimental" because we don't yet consider it production-ready,
+but everything's in place for you to start porting your apps to Python 3.
+Our next release, Django 1.6, will support Python 3 without reservations.
+
+Other notable new features in Django 1.5 include:
+
+* `Support for saving a subset of model's fields`_ -
+  :meth:`Model.save() <django.db.models.Model.save()>` now accepts an
+  ``update_fields`` argument, letting you specify which fields are
+  written back to the database when you call ``save()``. This can help
+  in high-concurrency operations, and can improve performance.
+
+* Better `support for streaming responses <#explicit-streaming-responses-beta-1>`_ via
+  the new  :class:`~django.http.StreamingHttpResponse` response class.
+
+* `GeoDjango`_ now supports PostGIS 2.0.
+
+* ... and more; `see below <#what-s-new-in-django-1-5>`_.
+
+Wherever possible we try to introduce new features in a backwards-compatible
+manner per :doc:`our API stability policy </misc/api-stability>`.
+However, as with previous releases, Django 1.5 ships with some minor
+`backwards incompatible changes`_; people upgrading from previous versions
+of Django should read that list carefully.
+
+One deprecated feature worth noting is the shift to "new-style" :ttag:`url` tag.
+Prior to Django 1.3, syntax like ``{% url myview %}`` was interpreted
+incorrectly (Django considered ``"myview"`` to be a literal name of a view, not
+a template variable named ``myview``). Django 1.3 and above introduced the
+``{% load url from future %}`` syntax to bring in the corrected behavior where
+``myview`` was seen as a variable.
+
+The upshot of this is that if you are not using ``{% load url from future %}``
+in your templates, you'll need to change tags like ``{% url myview %}`` to
+``{% url "myview" %}``. If you *were* using ``{% load url from future %}`` you
+can simply remove that line under Django 1.5
+
+Python compatibility
+====================
+
+Django 1.5 requires Python 2.6.5 or above, though we **highly recommended**
+Python 2.7.3 or above. Support for Python 2.5 and below as been dropped.
+
+This change should affect only a small number of Django users, as most
+operating-system vendors today are shipping Python 2.6 or newer as their default
+version. If you're still using Python 2.5, however, you'll need to stick to
+Django 1.4 until you can upgrade your Python version. Per :doc:`our support
+policy </internals/release-process>`, Django 1.4 will continue to receive
+security support until the release of Django 1.6.
+
+Django 1.5 does not run on a Jython final release, because Jython's latest
+release doesn't currently support Python 2.6. However, Jython currently does
+offer an alpha release featuring 2.7 support, and Django 1.5 supports that alpha
+release.
+
+Python 3 support
+~~~~~~~~~~~~~~~~
+
+Django 1.5 introduces support for Python 3 - specifically, Python
+3.2 and above. This comes in the form of a **single** codebase; you don't
+need to install a different version of Django on Python 3. This means that
+you can write application targeted for just Python 2, just Python 3, or single
+applications that support both platforms.
+
+However, we're labeling this support "experimental" for now: although it's
+received extensive testing via our automated test suite, it's received very
+little real-world testing. We've done our best to eliminate bugs, but we can't
+be sure we covered all possible uses of Django. Further, Django's more than a
+web framework; it's an ecosystem of pluggable components. At this point, very
+few third-party applications have been ported to Python 3, so it's unlikely
+that a real-world application will have all its dependencies satisfied under
+Python 3.
+
+Thus, we're recommending that Django 1.5 not be used in production under Python
+3. Instead, use this opportunity to begin :doc:`porting applications to Python 3
+</topics/python3>`. If you're an author of a pluggable component, we encourage you
+to start porting now.
+
+We plan to offer first-class, production-ready support for Python 3 in our next
+release, Django 1.6.
+
+What's new in Django 1.5
+========================
+
+Configurable User model
+~~~~~~~~~~~~~~~~~~~~~~~
+
+In Django 1.5, you can now use your own model as the store for user-related
+data. If your project needs a username with more than 30 characters, or if
+you want to store user's names in a format other than first name/last name,
+or you want to put custom profile information onto your User object, you can
+now do so.
+
+If you have a third-party reusable application that references the User model,
+you may need to make some changes to the way you reference User instances. You
+should also document any specific features of the User model that your
+application relies upon.
+
+See the :ref:`documentation on custom User models <auth-custom-user>` for
+more details.
+
+Support for saving a subset of model's fields
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The method :meth:`Model.save() <django.db.models.Model.save()>` has a new
+keyword argument ``update_fields``. By using this argument it is possible to
+save only a select list of model's fields. This can be useful for performance
+reasons or when trying to avoid overwriting concurrent changes.
+
+Deferred instances (those loaded by .only() or .defer()) will automatically
+save just the loaded fields. If any field is set manually after load, that
+field will also get updated on save.
+
+See the :meth:`Model.save() <django.db.models.Model.save()>` documentation for
+more details.
+
+Caching of related model instances
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When traversing relations, the ORM will avoid re-fetching objects that were
+previously loaded. For example, with the tutorial's models::
+
+    >>> first_poll = Poll.objects.all()[0]
+    >>> first_choice = first_poll.choice_set.all()[0]
+    >>> first_choice.poll is first_poll
+    True
+
+In Django 1.5, the third line no longer triggers a new SQL query to fetch
+``first_choice.poll``; it was set by the second line.
+
+For one-to-one relationships, both sides can be cached. For many-to-one
+relationships, only the single side of the relationship can be cached. This
+is particularly helpful in combination with ``prefetch_related``.
+
+.. _explicit-streaming-responses-beta-1:
+
+Explicit support for streaming responses
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Before Django 1.5, it was possible to create a streaming response by passing
+an iterator to :class:`~django.http.HttpResponse`. But this was unreliable:
+any middleware that accessed the :attr:`~django.http.HttpResponse.content`
+attribute would consume the iterator prematurely.
+
+You can now explicitly generate a streaming response with the new
+:class:`~django.http.StreamingHttpResponse` class. This class exposes a
+:class:`~django.http.StreamingHttpResponse.streaming_content` attribute which
+is an iterator.
+
+Since :class:`~django.http.StreamingHttpResponse` does not have a ``content``
+attribute, middleware that needs access to the response content must test for
+streaming responses and behave accordingly. See :ref:`response-middleware` for
+more information.
+
+``{% verbatim %}`` template tag
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To make it easier to deal with javascript templates which collide with Django's
+syntax, you can now use the :ttag:`verbatim` block tag to avoid parsing the
+tag's content.
+
+Retrieval of ``ContentType`` instances associated with proxy models
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The methods :meth:`ContentTypeManager.get_for_model() <django.contrib.contenttypes.models.ContentTypeManager.get_for_model()>`
+and :meth:`ContentTypeManager.get_for_models() <django.contrib.contenttypes.models.ContentTypeManager.get_for_models()>`
+have a new keyword argument – respectively ``for_concrete_model`` and ``for_concrete_models``.
+By passing ``False`` using this argument it is now possible to retrieve the
+:class:`ContentType <django.contrib.contenttypes.models.ContentType>`
+associated with proxy models.
+
+New ``view`` variable in class-based views context
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In all :doc:`generic class-based views </topics/class-based-views/index>`
+(or any class-based view inheriting from ``ContextMixin``), the context dictionary
+contains a ``view`` variable that points to the ``View`` instance.
+
+GeoDjango
+~~~~~~~~~
+
+* :class:`~django.contrib.gis.geos.LineString` and
+  :class:`~django.contrib.gis.geos.MultiLineString` GEOS objects now support the
+  :meth:`~django.contrib.gis.geos.GEOSGeometry.interpolate()` and
+  :meth:`~django.contrib.gis.geos.GEOSGeometry.project()` methods
+  (so-called linear referencing).
+
+* The wkb and hex properties of `GEOSGeometry` objects preserve the Z dimension.
+
+* Support for PostGIS 2.0 has been added and support for GDAL < 1.5 has been
+  dropped.
+
+Minor features
+~~~~~~~~~~~~~~
+
+Django 1.5 also includes several smaller improvements worth noting:
+
+* The template engine now interprets ``True``, ``False`` and ``None`` as the
+  corresponding Python objects.
+
+* :mod:`django.utils.timezone` provides a helper for converting aware
+  datetimes between time zones. See :func:`~django.utils.timezone.localtime`.
+
+* The generic views support OPTIONS requests.
+
+* Management commands do not raise ``SystemExit`` any more when called by code
+  from :ref:`call_command <call-command>`. Any exception raised by the command
+  (mostly :ref:`CommandError <ref-command-exceptions>`) is propagated.
+
+* The dumpdata management command outputs one row at a time, preventing
+  out-of-memory errors when dumping large datasets.
+
+* In the localflavor for Canada, "pq" was added to the acceptable codes for
+  Quebec. It's an old abbreviation.
+
+* The :ref:`receiver <connecting-receiver-functions>` decorator is now able to
+  connect to more than one signal by supplying a list of signals.
+
+* In the admin, you can now filter users by groups which they are members of.
+
+* :meth:`QuerySet.bulk_create()
+  <django.db.models.query.QuerySet.bulk_create>` now has a batch_size
+  argument. By default the batch_size is unlimited except for SQLite where
+  single batch is limited so that 999 parameters per query isn't exceeded.
+
+* The :setting:`LOGIN_URL` and :setting:`LOGIN_REDIRECT_URL` settings now also
+  accept view function names and
+  :ref:`named URL patterns <naming-url-patterns>`. This allows you to reduce
+  configuration duplication. More information can be found in the
+  :func:`~django.contrib.auth.decorators.login_required` documentation.
+
+* Django now provides a mod_wsgi :doc:`auth handler
+  </howto/deployment/wsgi/apache-auth>`.
+
+* The :meth:`QuerySet.delete() <django.db.models.query.QuerySet.delete>`
+  and :meth:`Model.delete() <django.db.models.Model.delete()>` can now take
+  fast-path in some cases. The fast-path allows for less queries and less
+  objects fetched into memory. See :meth:`QuerySet.delete()
+  <django.db.models.query.QuerySet.delete>` for details.
+
+* An instance of :class:`~django.core.urlresolvers.ResolverMatch` is stored on
+  the request as ``resolver_match``.
+
+* By default, all logging messages reaching the `django` logger when
+  :setting:`DEBUG` is `True` are sent to the console (unless you redefine the
+  logger in your :setting:`LOGGING` setting).
+
+* When using :class:`~django.template.RequestContext`, it is now possible to
+  look up permissions by using ``{% if 'someapp.someperm' in perms %}``
+  in templates.
+
+* It's not required any more to have ``404.html`` and ``500.html`` templates in
+  the root templates directory. Django will output some basic error messages for
+  both situations when those templates are not found. Of course, it's still
+  recommended as good practice to provide those templates in order to present
+  pretty error pages to the user.
+
+* :mod:`django.contrib.auth` provides a new signal that is emitted
+  whenever a user fails to login successfully. See
+  :data:`~django.contrib.auth.signals.user_login_failed`
+
+* The loaddata management command now supports an `ignorenonexistent` option to
+  ignore data for fields that no longer exist.
+
+* :meth:`~django.test.SimpleTestCase.assertXMLEqual` and
+  :meth:`~django.test.SimpleTestCase.assertXMLNotEqual` new assertions allow
+  you to test equality for XML content at a semantic level, without caring for
+  syntax differences (spaces, attribute order, etc.).
+
+* RemoteUserMiddleware now forces logout when the REMOTE_USER header
+  disappears during the same browser session.
+
+* The :ref:`cache-based session backend <cached-sessions-backend>` can store
+  session data in a non-default cache.
+
+* Multi-column indexes can now be created on models. Read the
+  :attr:`~django.db.models.Options.index_together` documentation for more
+  information.
+
+* During Django's logging configuration verbose Deprecation warnings are
+  enabled and warnings are captured into the logging system. Logged warnings
+  are routed through the ``console`` logging handler, which by default requires
+  :setting:`DEBUG` to be True for output to be generated. The result is that
+  DeprecationWarnings should be printed to the console in development
+  environments the way they have been in Python versions < 2.7.
+
+* The API for :meth:`django.contrib.admin.ModelAdmin.message_user` method has
+  been modified to accept additional arguments adding capabilities similar to
+  :func:`django.contrib.messages.add_message`. This is useful for generating
+  error messages from admin actions.
+
+* The admin's list filters can now be customized per-request thanks to the new
+  :meth:`django.contrib.admin.ModelAdmin.get_list_filter` method.
+
+Backwards incompatible changes in 1.5
+=====================================
+
+.. warning::
+
+    In addition to the changes outlined in this section, be sure to review the
+    :doc:`deprecation plan </internals/deprecation>` for any features that
+    have been removed. If you haven't updated your code within the
+    deprecation timeline for a given feature, its removal may appear as a
+    backwards incompatible change.
+
+Context in year archive class-based views
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For consistency with the other date-based generic views,
+:class:`~django.views.generic.dates.YearArchiveView` now passes ``year`` in
+the context as a :class:`datetime.date` rather than a string.  If you are
+using ``{{ year }}`` in your templates, you must replace it with ``{{
+year|date:"Y" }}``.
+
+``next_year`` and ``previous_year`` were also added in the context. They are
+calculated according to ``allow_empty`` and ``allow_future``.
+
+Context in year and month archive class-based views
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:class:`~django.views.generic.dates.YearArchiveView` and
+:class:`~django.views.generic.dates.MonthArchiveView` were documented to
+provide a ``date_list`` sorted in ascending order in the context, like their
+function-based predecessors, but it actually was in descending order. In 1.5,
+the documented order was restored. You may want to add (or remove) the
+``reversed`` keyword when you're iterating on ``date_list`` in a template::
+
+    {% for date in date_list reversed %}
+
+:class:`~django.views.generic.dates.ArchiveIndexView` still provides a
+``date_list`` in descending order.
+
+Context in TemplateView
+~~~~~~~~~~~~~~~~~~~~~~~
+
+For consistency with the design of the other generic views,
+:class:`~django.views.generic.base.TemplateView` no longer passes a ``params``
+dictionary into the context, instead passing the variables from the URLconf
+directly into the context.
+
+Non-form data in HTTP requests
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:attr:`request.POST <django.http.HttpRequest.POST>` will no longer include data
+posted via HTTP requests with non form-specific content-types in the header.
+In prior versions, data posted with content-types other than
+``multipart/form-data`` or ``application/x-www-form-urlencoded`` would still
+end up represented in the :attr:`request.POST <django.http.HttpRequest.POST>`
+attribute. Developers wishing to access the raw POST data for these cases,
+should use the :attr:`request.body <django.http.HttpRequest.body>` attribute
+instead.
+
+OPTIONS, PUT and DELETE requests in the test client
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Unlike GET and POST, these HTTP methods aren't implemented by web browsers.
+Rather, they're used in APIs, which transfer data in various formats such as
+JSON or XML. Since such requests may contain arbitrary data, Django doesn't
+attempt to decode their body.
+
+However, the test client used to build a query string for OPTIONS and DELETE
+requests like for GET, and a request body for PUT requests like for POST. This
+encoding was arbitrary and inconsistent with Django's behavior when it
+receives the requests, so it was removed in Django 1.5.
+
+If you were using the ``data`` parameter in an OPTIONS or a DELETE request,
+you must convert it to a query string and append it to the ``path`` parameter.
+
+If you were using the ``data`` parameter in a PUT request without a
+``content_type``, you must encode your data before passing it to the test
+client and set the ``content_type`` argument.
+
+.. _simplejson-incompatibilities-beta-1:
+
+System version of :mod:`simplejson` no longer used
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:ref:`As explained below <simplejson-deprecation-beta-1>`, Django 1.5 deprecates
+:mod:`django.utils.simplejson` in favor of Python 2.6's built-in :mod:`json`
+module. In theory, this change is harmless. Unfortunately, because of
+incompatibilities between versions of :mod:`simplejson`, it may trigger errors
+in some circumstances.
+
+JSON-related features in Django 1.4 always used :mod:`django.utils.simplejson`.
+This module was actually:
+
+- A system version of :mod:`simplejson`, if one was available (ie. ``import
+  simplejson`` works), if it was more recent than Django's built-in copy or it
+  had the C speedups, or
+- The :mod:`json` module from the standard library, if it was available (ie.
+  Python 2.6 or greater), or
+- A built-in copy of version 2.0.7 of :mod:`simplejson`.
+
+In Django 1.5, those features use Python's :mod:`json` module, which is based
+on version 2.0.9 of :mod:`simplejson`.
+
+There are no known incompatibilities between Django's copy of version 2.0.7 and
+Python's copy of version 2.0.9. However, there are some incompatibilities
+between other versions of :mod:`simplejson`:
+
+- While the :mod:`simplejson` API is documented as always returning unicode
+  strings, the optional C implementation can return a byte string. This was
+  fixed in Python 2.7.
+- :class:`simplejson.JSONEncoder` gained a ``namedtuple_as_object`` keyword
+  argument in version 2.2.
+
+More information on these incompatibilities is available in `ticket #18023`_.
+
+The net result is that, if you have installed :mod:`simplejson` and your code
+uses Django's serialization internals directly -- for instance
+:class:`django.core.serializers.json.DjangoJSONEncoder`, the switch from
+:mod:`simplejson` to :mod:`json` could break your code. (In general, changes to
+internals aren't documented; we're making an exception here.)
+
+At this point, the maintainers of Django believe that using :mod:`json` from
+the standard library offers the strongest guarantee of backwards-compatibility.
+They recommend to use it from now on.
+
+.. _ticket #18023: https://code.djangoproject.com/ticket/18023#comment:10
+
+String types of hasher method parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you have written a :ref:`custom password hasher <auth_password_storage>`,
+your ``encode()``, ``verify()`` or ``safe_summary()`` methods should accept
+Unicode parameters (``password``, ``salt`` or ``encoded``). If any of the
+hashing methods need byte strings, you can use the
+:func:`~django.utils.encoding.force_bytes` utility to encode the strings.
+
+Validation of previous_page_number and next_page_number
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When using :doc:`object pagination </topics/pagination>`,
+the ``previous_page_number()`` and ``next_page_number()`` methods of the
+:class:`~django.core.paginator.Page` object did not check if the returned
+number was inside the existing page range.
+It does check it now and raises an :exc:`InvalidPage` exception when the number
+is either too low or too high.
+
+Behavior of autocommit database option on PostgreSQL changed
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+PostgreSQL's autocommit option didn't work as advertised previously. It did
+work for single transaction block, but after the first block was left the
+autocommit behavior was never restored. This bug is now fixed in 1.5. While
+this is only a bug fix, it is worth checking your applications behavior if
+you are using PostgreSQL together with the autocommit option.
+
+Session not saved on 500 responses
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Django's session middleware will skip saving the session data if the
+response's status code is 500.
+
+Email checks on failed admin login
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Prior to Django 1.5, if you attempted to log into the admin interface and
+mistakenly used your email address instead of your username, the admin
+interface would provide a warning advising that your email address was
+not your username. In Django 1.5, the introduction of
+:ref:`custom User models <auth-custom-user>` has required the removal of this
+warning. This doesn't change the login behavior of the admin site; it only
+affects the warning message that is displayed under one particular mode of
+login failure.
+
+Changes in tests execution
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Some changes have been introduced in the execution of tests that might be
+backward-incompatible for some testing setups:
+
+Database flushing in ``django.test.TransactionTestCase``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Previously, the test database was truncated *before* each test run in a
+:class:`~django.test.TransactionTestCase`.
+
+In order to be able to run unit tests in any order and to make sure they are
+always isolated from each other, :class:`~django.test.TransactionTestCase` will
+now reset the database *after* each test run instead.
+
+No more implicit DB sequences reset
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:class:`~django.test.TransactionTestCase` tests used to reset primary key
+sequences automatically together with the database flushing actions described
+above.
+
+This has been changed so no sequences are implicitly reset. This can cause
+:class:`~django.test.TransactionTestCase` tests that depend on hard-coded
+primary key values to break.
+
+The new :attr:`~django.test.TransactionTestCase.reset_sequences` attribute can
+be used to force the old behavior for :class:`~django.test.TransactionTestCase`
+that might need it.
+
+Ordering of tests
+^^^^^^^^^^^^^^^^^
+
+In order to make sure all ``TestCase`` code starts with a clean database,
+tests are now executed in the following order:
+
+* First, all unittests (including :class:`unittest.TestCase`,
+  :class:`~django.test.SimpleTestCase`, :class:`~django.test.TestCase` and
+  :class:`~django.test.TransactionTestCase`) are run with no particular ordering
+  guaranteed nor enforced among them.
+
+* Then any other tests (e.g. doctests) that may alter the database without
+  restoring it to its original state are run.
+
+This should not cause any problems unless you have existing doctests which
+assume a :class:`~django.test.TransactionTestCase` executed earlier left some
+database state behind or unit tests that rely on some form of state being
+preserved after the execution of other tests. Such tests are already very
+fragile, and must now be changed to be able to run independently.
+
+`cleaned_data` dictionary kept for invalid forms
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The :attr:`~django.forms.Form.cleaned_data` dictionary is now always present
+after form validation. When the form doesn't validate, it contains only the
+fields that passed validation. You should test the success of the validation
+with the :meth:`~django.forms.Form.is_valid()` method and not with the
+presence or absence of the :attr:`~django.forms.Form.cleaned_data` attribute
+on the form.
+
+Behavior of :djadmin:`syncdb` with multiple databases
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:djadmin:`syncdb` now queries the database routers to determine if content
+types (when :mod:`~django.contrib.contenttypes` is enabled) and permissions
+(when :mod:`~django.contrib.auth` is enabled) should be created in the target
+database. Previously, it created them in the default database, even when
+another database was specified with the :djadminopt:`--database` option.
+
+If you use :djadmin:`syncdb` on multiple databases, you should ensure that
+your routers allow synchronizing content types and permissions to only one of
+them. See the docs on the :ref:`behavior of contrib apps with multiple
+databases <contrib_app_multiple_databases>` for more information.
+
+Miscellaneous
+~~~~~~~~~~~~~
+
+* :class:`django.forms.ModelMultipleChoiceField` now returns an empty
+  ``QuerySet`` as the empty value instead of an empty list.
+
+* :func:`~django.utils.http.int_to_base36` properly raises a :exc:`TypeError`
+  instead of :exc:`ValueError` for non-integer inputs.
+
+* The ``slugify`` template filter is now available as a standard python
+  function at :func:`django.utils.text.slugify`. Similarly, ``remove_tags`` is
+  available at :func:`django.utils.html.remove_tags`.
+
+* Uploaded files are no longer created as executable by default. If you need
+  them to be executable change :setting:`FILE_UPLOAD_PERMISSIONS` to your
+  needs. The new default value is `0666` (octal) and the current umask value
+  is first masked out.
+
+* The :ref:`F() expressions <query-expressions>` supported bitwise operators by
+  ``&`` and ``|``. These operators are now available using ``.bitand()`` and
+  ``.bitor()`` instead. The removal of ``&`` and ``|`` was done to be consistent with
+  :ref:`Q() expressions <complex-lookups-with-q>` and ``QuerySet`` combining where
+  the operators are used as boolean AND and OR operators.
+
+* In a ``filter()`` call, when :ref:`F() expressions <query-expressions>`
+  contained lookups spanning multi-valued relations, they didn't always reuse
+  the same relations as other lookups along the same chain. This was changed,
+  and now F() expressions will always use the same relations as other lookups
+  within the same ``filter()`` call.
+
+* The :ttag:`csrf_token` template tag is no longer enclosed in a div. If you need
+  HTML validation against pre-HTML5 Strict DTDs, you should add a div around it
+  in your pages.
+
+* The template tags library ``adminmedia``, which only contained the
+  deprecated template tag ``{% admin_media_prefix %}``, was removed.
+  Attempting to load it with ``{% load adminmedia %}`` will fail. If your
+  templates still contain that line you must remove it.
+
+Features deprecated in 1.5
+==========================
+
+.. _simplejson-deprecation-beta-1:
+
+:setting:`AUTH_PROFILE_MODULE`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+With the introduction of :ref:`custom User models <auth-custom-user>`, there is
+no longer any need for a built-in mechanism to store user profile data.
+
+You can still define user profiles models that have a one-to-one relation with
+the User model - in fact, for many applications needing to associate data with
+a User account, this will be an appropriate design pattern to follow. However,
+the :setting:`AUTH_PROFILE_MODULE` setting, and the
+:meth:`~django.contrib.auth.models.User.get_profile()` method for accessing
+the user profile model, should not be used any longer.
+
+Streaming behavior of :class:`HttpResponse`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Django 1.5 deprecates the ability to stream a response by passing an iterator
+to :class:`~django.http.HttpResponse`. If you rely on this behavior, switch to
+:class:`~django.http.StreamingHttpResponse`. See
+:ref:`explicit-streaming-responses-beta-1` above.
+
+In Django 1.7 and above, the iterator will be consumed immediately by
+:class:`~django.http.HttpResponse`.
+
+``django.utils.simplejson``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Since Django 1.5 drops support for Python 2.5, we can now rely on the
+:mod:`json` module being available in Python's standard library, so we've
+removed our own copy of :mod:`simplejson`. You should now import :mod:`json`
+instead :mod:`django.utils.simplejson`.
+
+Unfortunately, this change might have unwanted side-effects, because of
+incompatibilities between versions of :mod:`simplejson` -- see the
+:ref:`backwards-incompatible changes <simplejson-incompatibilities-beta-1>` section.
+If you rely on features added to :mod:`simplejson` after it became Python's
+:mod:`json`, you should import :mod:`simplejson` explicitly.
+
+``django.utils.encoding.StrAndUnicode``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The :class:`~django.utils.encoding.StrAndUnicode` mix-in has been deprecated.
+Define a ``__str__`` method and apply the
+:func:`~django.utils.encoding.python_2_unicode_compatible` decorator instead.
+
+``django.utils.itercompat.product``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The :func:`~django.utils.itercompat.product` function has been deprecated. Use
+the built-in :func:`itertools.product` instead.
+
+``django.utils.markup``
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The markup contrib module has been deprecated and will follow an accelerated
+deprecation schedule. Direct use of python markup libraries or 3rd party tag
+libraries is preferred to Django maintaining this functionality in the
+framework.
+
+``cleanup`` management command
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The :djadmin:`cleanup` management command has been deprecated and replaced by
+:djadmin:`clearsessions`.
+
+``daily_cleanup.py`` script
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The undocumented ``daily_cleanup.py`` script has been deprecated. Use the
+:djadmin:`clearsessions` management command instead.
+
+``depth`` keyword argument in ``select_related``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``depth`` keyword argument in
+:meth:`~django.db.models.query.QuerySet.select_related` has been deprecated.
+You should use field names instead.

docs/releases/index.txt

@@ -92,6 +92,7 @@ notes.
 .. toctree::
    :maxdepth: 1
 
+   1.5-beta-1
    1.5-alpha-1
    1.4-beta-1
    1.4-alpha-1