diff --git a/docs/releases/1.4.txt b/docs/releases/1.4.txt index 211d1362c8..8d0cd753c5 100644 --- a/docs/releases/1.4.txt +++ b/docs/releases/1.4.txt @@ -1,20 +1,64 @@ -============================================ -Django 1.4 release notes - UNDER DEVELOPMENT -============================================ +======================== +Django 1.4 release notes +======================== -This page documents release notes for the as-yet-unreleased Django -1.4. As such, it's tentative and subject to change. It provides -up-to-date information for those who are following trunk. +*March 23, 2012* -Django 1.4 includes various `new features`_ and some minor `backwards -incompatible changes`_. We've also dropped some features, which are detailed -in :doc:`our deprecation plan `, and we've -`begun the deprecation process for some features`_. +Welcome to Django 1.4! + +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.3 or older versions. We've also dropped some +features, which are detailed in :doc:`our deprecation plan +`, and we've `begun the deprecation process for some +features`_. .. _`new features`: `What's new in Django 1.4`_ .. _`backwards incompatible changes`: `Backwards incompatible changes in 1.4`_ .. _`begun the deprecation process for some features`: `Features deprecated in 1.4`_ +Overview +======== + +The biggest new feature in Django 1.4 is `support for time zones`_ when +handling date/times. When enabled, this Django will store date/times in UTC, +use timezone-aware objects internally, and translate them to users' local +timezones for display. + +If you're upgrading an existing project to Django 1.4, switching to the time- +zone aware mode may take some care: the new mode disallows some rather sloppy +behavior that used to be accepted. We encourage anyone who's upgrading to check +out the :ref:`timezone migration guide ` and the +:ref:`timezone FAQ ` for useful pointers. + +Other notable new features in Django 1.4 include: + +* A number of ORM improvements, including `SELECT FOR UPDATE support`_, + the ability to `bulk insert `_ + large datasets for improved performance, and + `QuerySet.prefetch_related`_, a method to batch-load related objects + in areas where :meth:`~django.db.models.QuerySet.select_related` does't + work. + +* Some nice security additions, including `improved password hashing`_ + (featuring PBKDF2_ and bcrypt_ support), new `tools for cryptographic + signing`_, several `CSRF improvements`_, and `simple clickjacking + protection`_. + +* An `updated default project layout and manage.py`_ that removes the "magic" + from prior versions. And for those who don't like the new layout, you can + use `custom project and app templates`_ instead! + +* `Support for in-browser testing frameworks`_ (like Selenium_). + +* ... and a whole lot more; `see below `_! + +Wherever possible we try to introduce new features in a backwards-compatible +manner per :doc:`our API stability policy ` policy. +However, as with previous releases, Django 1.4 ships with some minor +`backwards incompatible changes`_; people upgrading from previous versions +of Django should read that list carefully. + Python compatibility ==================== @@ -36,6 +80,33 @@ timeline for deprecating Python 2.x and moving to Python 3.x. What's new in Django 1.4 ======================== +Support for time zones +~~~~~~~~~~~~~~~~~~~~~~ + +In previous versions, Django used "naive" date/times (that is, date/times +without an associated time zone), leaving it up to each developer to interpret +what a given date/time "really means". This can cause all sorts of subtle +timezone-related bugs. + +In Django 1.4, you can now switch Django into a more correct, time-zone aware +mode. In this mode, Django stores date and time information in UTC in the +database, uses time-zone-aware datetime objects internally and translates them +to the end user's time zone in templates and forms. Reasons for using this +feature include: + +- Customizing date and time display for users around the world. + +- Storing datetimes in UTC for database portability and interoperability. + (This argument doesn't apply to PostgreSQL, because it already stores + timestamps with time zone information in Django 1.3.) + +- Avoiding data corruption problems around DST transitions. + +Time zone support is enabled by default in new projects created with +:djadmin:`startproject`. If you want to use this feature in an existing +project, read the :ref:`migration guide `. If you +encounter problems, there's a helpful :ref:`FAQ `. + Support for in-browser testing frameworks ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -48,6 +119,110 @@ concrete examples. .. _Selenium: http://seleniumhq.org/ +Updated default project layout and ``manage.py`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Django 1.4 ships with an updated default project layout and ``manage.py`` file +for the :djadmin:`startproject` management command. These fix some issues with +the previous ``manage.py`` handling of Python import paths that caused double +imports, trouble moving from development to deployment, and other +difficult-to-debug path issues. + +The previous ``manage.py`` called functions that are now deprecated, and thus +projects upgrading to Django 1.4 should update their ``manage.py``. (The +old-style ``manage.py`` will continue to work as before until Django 1.6. In +1.5 it will raise ``DeprecationWarning``). + +The new recommended ``manage.py`` file should look like this:: + + #!/usr/bin/env python + import os, sys + + if __name__ == "__main__": + os.environ.setdefault("DJANGO_SETTINGS_MODULE", "{{ project_name }}.settings") + + from django.core.management import execute_from_command_line + + execute_from_command_line(sys.argv) + +``{{ project_name }}`` should be replaced with the Python package name of the +actual project. + +If settings, URLconfs and apps within the project are imported or referenced +using the project name prefix (e.g. ``myproject.settings``, ``ROOT_URLCONF = +"myproject.urls"``, etc), the new ``manage.py`` will need to be moved one +directory up, so it is outside the project package rather than adjacent to +``settings.py`` and ``urls.py``. + +For instance, with the following layout:: + + manage.py + mysite/ + __init__.py + settings.py + urls.py + myapp/ + __init__.py + models.py + +You could import ``mysite.settings``, ``mysite.urls``, and ``mysite.myapp``, +but not ``settings``, ``urls``, or ``myapp`` as top-level modules. + +Anything imported as a top-level module can be placed adjacent to the new +``manage.py``. For instance, to decouple "myapp" from the project module and +import it as just ``myapp``, place it outside the ``mysite/`` directory:: + + manage.py + myapp/ + __init__.py + models.py + mysite/ + __init__.py + settings.py + urls.py + +If the same code is imported inconsistently (some places with the project +prefix, some places without it), the imports will need to be cleaned up when +switching to the new ``manage.py``. + +Custom project and app templates +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The :djadmin:`startapp` and :djadmin:`startproject` management commands +now have a ``--template`` option for specifying a path or URL to a custom app +or project template. + +For example, Django will use the ``/path/to/my_project_template`` directory +when you run the following command:: + + django-admin.py startproject --template=/path/to/my_project_template myproject + +You can also now provide a destination directory as the second +argument to both :djadmin:`startapp` and :djadmin:`startproject`:: + + django-admin.py startapp myapp /path/to/new/app + django-admin.py startproject myproject /path/to/new/project + +For more information, see the :djadmin:`startapp` and :djadmin:`startproject` +documentation. + +Improved WSGI support +~~~~~~~~~~~~~~~~~~~~~ + +The :djadmin:`startproject` management command now adds a :file:`wsgi.py` +module to the initial project layout, containing a simple WSGI application that +can be used for :doc:`deploying with WSGI app +servers`. + +The :djadmin:`built-in development server` now supports using an +externally-defined WSGI callable, which makes it possible to run runserver +with the same WSGI configuration that is used for deployment. The new +:setting:`WSGI_APPLICATION` setting lets you configure which WSGI callable +:djadmin:`runserver` uses. + +(The :djadmin:`runfcgi` management command also internally wraps the WSGI +callable configured via :setting:`WSGI_APPLICATION`.) + ``SELECT FOR UPDATE`` support ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -184,7 +359,7 @@ more information. New form wizard ~~~~~~~~~~~~~~~ -The previous ``FormWizard`` from the formtools contrib app has been +The previous ``FormWizard`` from :mod:`django.contrib.formtools` has been replaced with a new implementation based on the class-based views introduced in Django 1.3. It features a pluggable storage API and doesn't require the wizard to pass around hidden fields for every previous step. @@ -350,137 +525,11 @@ filter`. For more information see the docs on Extended IPv6 support ~~~~~~~~~~~~~~~~~~~~~ -The previously added support for IPv6 addresses when using the runserver -management command in Django 1.3 has been extended with -a :class:`~django.db.models.fields.GenericIPAddressField` model field, -a :class:`~django.forms.fields.GenericIPAddressField` form field and +Django 1.4 can now better handle IPv6 addresses with the new +:class:`~django.db.models.fields.GenericIPAddressField` model field, +:class:`~django.forms.fields.GenericIPAddressField` form field and the validators :data:`~django.core.validators.validate_ipv46_address` and -:data:`~django.core.validators.validate_ipv6_address` - -Updated default project layout and ``manage.py`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Django 1.4 ships with an updated default project layout and ``manage.py`` file -for the :djadmin:`startproject` management command. These fix some issues with -the previous ``manage.py`` handling of Python import paths that caused double -imports, trouble moving from development to deployment, and other -difficult-to-debug path issues. - -The previous ``manage.py`` called functions that are now deprecated, and thus -projects upgrading to Django 1.4 should update their ``manage.py``. (The -old-style ``manage.py`` will continue to work as before until Django 1.6. In -1.5 it will raise ``DeprecationWarning``). - -The new recommended ``manage.py`` file should look like this:: - - #!/usr/bin/env python - import os, sys - - if __name__ == "__main__": - os.environ.setdefault("DJANGO_SETTINGS_MODULE", "{{ project_name }}.settings") - - from django.core.management import execute_from_command_line - - execute_from_command_line(sys.argv) - -``{{ project_name }}`` should be replaced with the Python package name of the -actual project. - -If settings, URLconfs and apps within the project are imported or referenced -using the project name prefix (e.g. ``myproject.settings``, ``ROOT_URLCONF = -"myproject.urls"``, etc), the new ``manage.py`` will need to be moved one -directory up, so it is outside the project package rather than adjacent to -``settings.py`` and ``urls.py``. - -For instance, with the following layout:: - - manage.py - mysite/ - __init__.py - settings.py - urls.py - myapp/ - __init__.py - models.py - -You could import ``mysite.settings``, ``mysite.urls``, and ``mysite.myapp``, -but not ``settings``, ``urls``, or ``myapp`` as top-level modules. - -Anything imported as a top-level module can be placed adjacent to the new -``manage.py``. For instance, to decouple "myapp" from the project module and -import it as just ``myapp``, place it outside the ``mysite/`` directory:: - - manage.py - myapp/ - __init__.py - models.py - mysite/ - __init__.py - settings.py - urls.py - -If the same code is imported inconsistently (some places with the project -prefix, some places without it), the imports will need to be cleaned up when -switching to the new ``manage.py``. - -Improved WSGI support -~~~~~~~~~~~~~~~~~~~~~ - -The :djadmin:`startproject` management command now adds a :file:`wsgi.py` -module to the initial project layout, containing a simple WSGI application that -can be used for :doc:`deploying with WSGI app -servers`. - -The :djadmin:`built-in development server` now supports using an -externally-defined WSGI callable, which makes it possible to run runserver -with the same WSGI configuration that is used for deployment. The new -:setting:`WSGI_APPLICATION` setting lets you configure which WSGI callable -:djadmin:`runserver` uses. - -(The :djadmin:`runfcgi` management command also internally wraps the WSGI -callable configured via :setting:`WSGI_APPLICATION`.) - -Custom project and app templates -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The :djadmin:`startapp` and :djadmin:`startproject` management commands -now have a ``--template`` option for specifying a path or URL to a custom app -or project template. - -For example, Django will use the ``/path/to/my_project_template`` directory -when you run the following command:: - - django-admin.py startproject --template=/path/to/my_project_template myproject - -You can also now provide a destination directory as the second -argument to both :djadmin:`startapp` and :djadmin:`startproject`:: - - django-admin.py startapp myapp /path/to/new/app - django-admin.py startproject myproject /path/to/new/project - -For more information, see the :djadmin:`startapp` and :djadmin:`startproject` -documentation. - -Support for time zones -~~~~~~~~~~~~~~~~~~~~~~ - -Django 1.4 adds :ref:`support for time zones `. When it's enabled, -Django stores date and time information in UTC in the database, uses -time-zone-aware datetime objects internally and translates them to the end user's -time zone in templates and forms. - -Reasons for using this feature include: - -- Customizing date and time display for users around the world. -- Storing datetimes in UTC for database portability and interoperability. - (This argument doesn't apply to PostgreSQL, because it already stores - timestamps with time zone information in Django 1.3.) -- Avoiding data corruption problems around DST transitions. - -Time zone support is enabled by default in new projects created with -:djadmin:`startproject`. If you want to use this feature in an existing -project, read the :ref:`migration guide `. If you -encounter problems, there's a helpful :ref:`FAQ `. +:data:`~django.core.validators.validate_ipv6_address`. HTML comparisons in tests ~~~~~~~~~~~~~~~~~~~~~~~~~