Edited Django 1.4 release notes:

* Remove the "UNDER DEVELOPMENT" parts.
* Added an overview, explicitly mentioning time zone support.
* Spell/grammar check.

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

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 </internals/deprecation>`, 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
+</internals/deprecation>`, 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 <time-zones-migration-guide>` and the
+:ref:`timezone FAQ <time-zones-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 <Model.objects.bulk_create in the ORM>`_
+  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 <what's new in django 1.4>`_!
+
+Wherever possible we try to introduce new features in a backwards-compatible
+manner per :doc:`our API stability policy </misc/api-stability>` 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 <time-zones-migration-guide>`. If you
+encounter problems, there's a helpful :ref:`FAQ <time-zones-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</howto/deployment/wsgi/index>`.
+
+The :djadmin:`built-in development server<runserver>` 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<custom-error-reports>`. 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</howto/deployment/wsgi/index>`.
-
-The :djadmin:`built-in development server<runserver>` 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 <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 <time-zones-migration-guide>`. If you
-encounter problems, there's a helpful :ref:`FAQ <time-zones-faq>`.
+:data:`~django.core.validators.validate_ipv6_address`.
 
 HTML comparisons in tests
 ~~~~~~~~~~~~~~~~~~~~~~~~~