django/docs/releases/1.6.txt

============================================
Django 1.6 release notes - UNDER DEVELOPMENT
============================================

Welcome to Django 1.6!

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.5 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.6`_
.. _`backwards incompatible changes`: `Backwards incompatible changes in 1.6`_
.. _`begun the deprecation process for some features`: `Features deprecated in 1.6`_

What's new in Django 1.6
========================

Simplified default project and app templates
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The default templates used by :djadmin:`startproject` and :djadmin:`startapp`
have been simplified and modernized. The :doc:`admin
</ref/contrib/admin/index>` is now enabled by default in new projects; the
:doc:`sites </ref/contrib/sites>` framework no longer is. :ref:`Language
detection <how-django-discovers-language-preference>` and :ref:`clickjacking
prevention <clickjacking-prevention>` are turned on.

If the default templates don't suit your tastes, you can use :ref:`custom
project and app templates <custom-app-and-project-templates>`.

Time zone aware aggregation
~~~~~~~~~~~~~~~~~~~~~~~~~~~

The support for :doc:`time zones </topics/i18n/timezones>` introduced in
Django 1.4 didn't work well with :meth:`QuerySet.dates()
<django.db.models.query.QuerySet.dates>`: aggregation was always performed in
UTC. This limitation was lifted in Django 1.6. Use :meth:`QuerySet.datetimes()
<django.db.models.query.QuerySet.datetimes>` to perform time zone aware
aggregation on a :class:`~django.db.models.DateTimeField`.

Minor features
~~~~~~~~~~~~~~

* Authentication backends can raise ``PermissionDenied`` to immediately fail
  the authentication chain.

* The HttpOnly flag can be set on the CSRF cookie with
  :setting:`CSRF_COOKIE_HTTPONLY`.

* The ``assertQuerysetEqual()`` now checks for undefined order and raises
  ``ValueError`` if undefined order is spotted. The order is seen as
  undefined if the given ``QuerySet`` isn't ordered and there are more than
  one ordered values to compare against.

* Added :meth:`~django.db.models.query.QuerySet.earliest` for symmetry with
  :meth:`~django.db.models.query.QuerySet.latest`.

* In addition to :lookup:`year`, :lookup:`month` and :lookup:`day`, the ORM
  now supports :lookup:`hour`, :lookup:`minute` and :lookup:`second` lookups.

* The default widgets for :class:`~django.forms.EmailField` and
  :class:`~django.forms.URLField` use the new type attributes available in
  HTML5 (type='email', type='url').

* The ``number`` argument for :ref:`lazy plural translations
  <lazy-plural-translations>` can be provided at translation time rather than
  at definition time.

* For custom management commands: Verification of the presence of valid
  settings in commands that ask for it by using the
  :attr:`~django.core.management.BaseCommand.can_import_settings` internal
  option is now performed independently from handling of the locale that
  should be active during the execution of the command. The latter can now be
  influenced by the new
  :attr:`~django.core.management.BaseCommand.leave_locale_alone` internal
  option. See :ref:`management-commands-and-locales` for more details.

* The :attr:`~django.views.generic.edit.DeletionMixin.success_url` of
  :class:`~django.views.generic.edit.DeletionMixin` is now interpolated with
  its ``object``\'s ``__dict__``.

* :class:`~django.http.HttpResponseRedirect` and
  :class:`~django.http.HttpResponsePermanentRedirect` now provide an ``url``
  attribute (equivalent to the URL the response will redirect to).

Backwards incompatible changes in 1.6
=====================================

* The ``django.db.models.query.EmptyQuerySet`` can't be instantiated any more -
  it is only usable as a marker class for checking if
  :meth:`~django.db.models.query.QuerySet.none` has been called:
  ``isinstance(qs.none(), EmptyQuerySet)``

* :meth:`QuerySet.dates() <django.db.models.query.QuerySet.dates>` raises an
  error if it's used on :class:`~django.db.models.DateTimeField` when time
  zone support is active. Use :meth:`QuerySet.datetimes()
  <django.db.models.query.QuerySet.datetimes>` instead.

* :meth:`QuerySet.dates() <django.db.models.query.QuerySet.dates>` returns a
  list of :class:`~datetime.date`. It used to return a list of
  :class:`~datetime.datetime`.

* The :attr:`~django.contrib.admin.ModelAdmin.date_hierarchy` feature of the
  admin on a :class:`~django.db.models.DateTimeField` requires time zone
  definitions in the database when :setting:`USE_TZ` is ``True``.
  :ref:`Learn more <database-time-zone-definitions>`.

* Accessing ``date_list`` in the context of a date-based generic view requires
  time zone definitions in the database when the view is based on a
  :class:`~django.db.models.DateTimeField` and :setting:`USE_TZ` is ``True``.
  :ref:`Learn more <database-time-zone-definitions>`.

* Model fields named ``hour``, ``minute`` or ``second`` may clash with the new
  lookups. Append an explicit :lookup:`exact` lookup if this is an issue.

* If your CSS/Javascript code used to access HTML input widgets by type, you
  should review it as ``type='text'`` widgets might be now output as
  ``type='email'`` or ``type='url'`` depending on their corresponding field type.

* Extraction of translatable literals from templates with the
  :djadmin:`makemessages` command now correctly detects i18n constructs when
  they are located after a ``{#`` / ``#}``-type comment on the same line. E.g.:

  .. code-block:: html+django

    {# A comment #}{% trans "This literal was incorrectly ignored. Not anymore" %}

* (Related to the above item.) Validation of the placement of
  :ref:`translator-comments-in-templates` specified using ``{#`` / ``#}`` is now
  stricter. All translator comments not located at the end of their respective
  lines in a template are ignored and a warning is generated by
  :djadmin:`makemessages` when it finds them. E.g.:

  .. code-block:: html+django

    {# Translators: This is ignored #}{% trans "Translate me" %}
    {{ title }}{# Translators: Extracted and associated with 'Welcome' below #}
    <h1>{% trans "Welcome" %}</h1>

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

Features deprecated in 1.6
==========================

``SEND_BROKEN_LINK_EMAILS`` setting
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:class:`~django.middleware.common.CommonMiddleware` used to provide basic
reporting of broken links by email when ``SEND_BROKEN_LINK_EMAILS`` is set to
``True``.

Because of intractable ordering problems between
:class:`~django.middleware.common.CommonMiddleware` and
:class:`~django.middleware.locale.LocaleMiddleware`, this feature was split
out into a new middleware:
:class:`~django.middleware.common.BrokenLinkEmailsMiddleware`.

If you're relying on this feature, you should add
``'django.middleware.common.BrokenLinkEmailsMiddleware'`` to your
:setting:`MIDDLEWARE_CLASSES` setting and remove ``SEND_BROKEN_LINK_EMAILS``
from your settings.

``_has_changed`` method on widgets
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you defined your own form widgets and defined the ``_has_changed`` method
on a widget, you should now define this method on the form field itself.

``module_name`` model meta attribute
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``Model._meta.module_name`` was renamed to ``model_name``. Despite being a
private API, it will go through a regular deprecation path.