Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Corrections and improvements to the 1.4 release notes.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@17252 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit a976159db0d40d8e1bd1a7bc70f7508839e8a95d 1 parent a0721a3
authored
261  docs/releases/1.4-alpha-1.txt
@@ -50,7 +50,7 @@ What's new in Django 1.4
50 50
 Support for in-browser testing frameworks
51 51
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
52 52
 
53  
-Django 1.4 now supports the integration with in-browser testing frameworks such
  53
+Django 1.4 now supports integration with in-browser testing frameworks such
54 54
 as Selenium_ or Windmill_ thanks to the :class:`django.test.LiveServerTestCase`
55 55
 base class, allowing you to test the interactions between your site's front and
56 56
 back ends more comprehensively. See the
@@ -90,56 +90,55 @@ Similar to :meth:`~django.db.models.query.QuerySet.select_related` but with a
90 90
 different strategy and broader scope,
91 91
 :meth:`~django.db.models.query.QuerySet.prefetch_related` has been added to
92 92
 :class:`~django.db.models.query.QuerySet`. This method returns a new
93  
-``QuerySet`` that will prefetch in a single batch each of the specified related
94  
-lookups as soon as it begins to be evaluated. Unlike ``select_related``, it does
95  
-the joins in Python, not in the database, and supports many-to-many
96  
-relationships, :class:`~django.contrib.contenttypes.generic.GenericForeignKey`
97  
-and more. This enables you to fix many instances of a very common performance
98  
-problem, in which your code ends up doing O(n) database queries (or worse) if
99  
-objects on your primary ``QuerySet`` each have many related objects that you
100  
-also need.
101  
-
102  
-HTML5
103  
-~~~~~
  93
+``QuerySet`` that will prefetch each of the specified related lookups in a
  94
+single batch as soon as the query begins to be evaluated. Unlike
  95
+``select_related``, it does the joins in Python, not in the database, and
  96
+supports many-to-many relationships,
  97
+:class:`~django.contrib.contenttypes.generic.GenericForeignKey` and more. This
  98
+allows you to fix a very common performance problem in which your code ends up
  99
+doing O(n) database queries (or worse) if objects on your primary ``QuerySet``
  100
+each have many related objects that you also need.
  101
+
  102
+HTML5 Doctype
  103
+~~~~~~~~~~~~~
104 104
 
105 105
 We've switched the admin and other bundled templates to use the HTML5
106  
-doctype. While Django will be careful in its use of HTML5 features, to maintain
107  
-compatibility with older browsers, this change means that you can use any HTML5
108  
-features you need in admin pages without having to lose HTML validity or
109  
-override the provided templates to change the doctype.
  106
+doctype. While Django will be careful to maintain compatibility with older
  107
+browsers, this change means that you can use any HTML5 features you need in
  108
+admin pages without having to lose HTML validity or override the provided
  109
+templates to change the doctype.
110 110
 
111 111
 List filters in admin interface
112 112
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
113 113
 
114  
-Prior to Django 1.4, the Django admin app allowed specifying change list
115  
-filters by specifying a field lookup (including spanning relations), and
116  
-not custom filters. This has been rectified with a simple API previously
117  
-known as "FilterSpec" which was used internally. For more details, see the
118  
-documentation for :attr:`~django.contrib.admin.ModelAdmin.list_filter`.
  114
+Prior to Django 1.4, the :mod:`~django.contrib.admin` app allowed you to specify
  115
+change list filters by specifying a field lookup, but didn't allow you to create
  116
+custom filters. This has been rectified with a simple API (previously used
  117
+internally and known as "FilterSpec"). For more details, see the documentation
  118
+for :attr:`~django.contrib.admin.ModelAdmin.list_filter`.
119 119
 
120 120
 Multiple sort in admin interface
121 121
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
122 122
 
123  
-The admin change list now supports sorting on multiple columns. It respects
124  
-all elements of the :attr:`~django.contrib.admin.ModelAdmin.ordering`
125  
-attribute, and sorting on multiple columns by clicking on headers is designed
126  
-to work similarly to how desktop GUIs do it. The new hook
127  
-:meth:`~django.contrib.admin.ModelAdmin.get_ordering` for specifying the
  123
+The admin change list now supports sorting on multiple columns. It respects all
  124
+elements of the :attr:`~django.contrib.admin.ModelAdmin.ordering` attribute, and
  125
+sorting on multiple columns by clicking on headers is designed to mimic the
  126
+behavior of desktop GUIs. The
  127
+:meth:`~django.contrib.admin.ModelAdmin.get_ordering` method for specifying the
128 128
 ordering dynamically (e.g. depending on the request) has also been added.
129 129
 
130 130
 New ``ModelAdmin`` methods
131 131
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
132 132
 
133 133
 A new :meth:`~django.contrib.admin.ModelAdmin.save_related` method was added to
134  
-:mod:`~django.contrib.admin.ModelAdmin` to ease the customization of how
  134
+:mod:`~django.contrib.admin.ModelAdmin` to ease customization of how
135 135
 related objects are saved in the admin.
136 136
 
137 137
 Two other new methods,
138 138
 :meth:`~django.contrib.admin.ModelAdmin.get_list_display` and
139 139
 :meth:`~django.contrib.admin.ModelAdmin.get_list_display_links`
140 140
 were added to :class:`~django.contrib.admin.ModelAdmin` to enable the dynamic
141  
-customization of fields and links to display on the admin
142  
-change list.
  141
+customization of fields and links displayed on the admin change list.
143 142
 
144 143
 Admin inlines respect user permissions
145 144
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -157,30 +156,31 @@ Django 1.4 adds both a low-level API for signing values and a high-level API
157 156
 for setting and reading signed cookies, one of the most common uses of
158 157
 signing in Web applications.
159 158
 
160  
-See :doc:`cryptographic signing </topics/signing>` docs for more information.
  159
+See the :doc:`cryptographic signing </topics/signing>` docs for more
  160
+information.
161 161
 
162 162
 Cookie-based session backend
163 163
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
164 164
 
165  
-Django 1.4 introduces a new cookie based backend for the session framework
  165
+Django 1.4 introduces a new cookie-based backend for the session framework
166 166
 which uses the tools for :doc:`cryptographic signing </topics/signing>` to
167 167
 store the session data in the client's browser.
168 168
 
169  
-See the :ref:`cookie-based backend <cookie-session-backend>` docs for
  169
+See the :ref:`cookie-based session backend <cookie-session-backend>` docs for
170 170
 more information.
171 171
 
172 172
 New form wizard
173 173
 ~~~~~~~~~~~~~~~
174 174
 
175  
-The previously shipped ``FormWizard`` of the formtools contrib app has been
176  
-replaced with a new implementation that is based on the class based views
  175
+The previous ``FormWizard`` from the formtools contrib app has been
  176
+replaced with a new implementation based on the class-based views
177 177
 introduced in Django 1.3. It features a pluggable storage API and doesn't
178 178
 require the wizard to pass around hidden fields for every previous step.
179 179
 
180  
-Django 1.4 ships with a session based storage backend and a cookie based
  180
+Django 1.4 ships with a session-based storage backend and a cookie-based
181 181
 storage backend. The latter uses the tools for
182 182
 :doc:`cryptographic signing </topics/signing>` also introduced in
183  
-Django 1.4 to store the wizard state in the user's cookies.
  183
+Django 1.4 to store the wizard's state in the user's cookies.
184 184
 
185 185
 See the :doc:`form wizard </ref/contrib/formtools/form-wizard>` docs for
186 186
 more information.
@@ -195,7 +195,7 @@ Translating URL patterns
195 195
 ~~~~~~~~~~~~~~~~~~~~~~~~
196 196
 
197 197
 Django 1.4 gained the ability to look for a language prefix in the URL pattern
198  
-when using the new :func:`django.conf.urls.i18n.i18n_patterns` helper function.
  198
+when using the new :func:`~django.conf.urls.i18n.i18n_patterns` helper function.
199 199
 Additionally, it's now possible to define translatable URL patterns using
200 200
 :func:`~django.utils.translation.ugettext_lazy`. See
201 201
 :ref:`url-internationalization` for more information about the language prefix
@@ -204,34 +204,35 @@ and how to internationalize URL patterns.
204 204
 Contextual translation support for ``{% trans %}`` and ``{% blocktrans %}``
205 205
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
206 206
 
207  
-Django 1.3 introduced :ref:`contextual translation<contextual-markers>` support
208  
-in Python files via the ``pgettext`` function. This is now also supported by
209  
-the :ttag:`trans` and :ttag:`blocktrans` template tags using the new
210  
-``context`` keyword.
  207
+The :ref:`contextual translation<contextual-markers>` support introduced in
  208
+Django 1.3 via the ``pgettext`` function has been extended to the
  209
+:ttag:`trans` and :ttag:`blocktrans` template tags using the new ``context``
  210
+keyword.
211 211
 
212 212
 Customizable ``SingleObjectMixin`` URLConf kwargs
213 213
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
214 214
 
215 215
 Two new attributes,
216  
-:attr:`pk_url_kwarg<django.views.generic.detail.SingleObjectMixin.pk_url_kwarg>` and
  216
+:attr:`pk_url_kwarg<django.views.generic.detail.SingleObjectMixin.pk_url_kwarg>`
  217
+and
217 218
 :attr:`slug_url_kwarg<django.views.generic.detail.SingleObjectMixin.slug_url_kwarg>`,
218  
-have been added to :class:`django.views.generic.detail.SingleObjectMixin` to
  219
+have been added to :class:`~django.views.generic.detail.SingleObjectMixin` to
219 220
 enable the customization of URLConf keyword arguments used for single
220 221
 object generic views.
221 222
 
222 223
 Assignment template tags
223 224
 ~~~~~~~~~~~~~~~~~~~~~~~~
224 225
 
225  
-A new helper function,
226  
-:ref:`assignment_tag<howto-custom-template-tags-assignment-tags>`, was added to
227  
-``template.Library`` to ease the creation of template tags that store some
228  
-data in a specified context variable.
  226
+A new :ref:`assignment_tag<howto-custom-template-tags-assignment-tags>` helper
  227
+function was added to ``template.Library`` to ease the creation of template
  228
+tags that store data in a specified context variable.
229 229
 
230 230
 ``*args`` and ``**kwargs`` support for template tag helper functions
231 231
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
232 232
 
233  
-:ref:`simple_tag<howto-custom-template-tags-simple-tags>`, :ref:`inclusion_tag
234  
-<howto-custom-template-tags-inclusion-tags>` and the newly introduced
  233
+The :ref:`simple_tag<howto-custom-template-tags-simple-tags>`,
  234
+:ref:`inclusion_tag <howto-custom-template-tags-inclusion-tags>` and
  235
+newly introduced
235 236
 :ref:`assignment_tag<howto-custom-template-tags-assignment-tags>` template
236 237
 helper functions may now accept any number of positional or keyword arguments.
237 238
 For example:
@@ -272,25 +273,25 @@ exceptions from template rendering is now consistent regardless of the value of
272 273
 
273 274
 Added a filter which truncates a string to be no longer than the specified
274 275
 number of characters. Truncated strings end with a translatable ellipsis
275  
-sequence ("..."). See the :tfilter:`truncatechars docs <truncatechars>` for
  276
+sequence ("..."). See the documentation for :tfilter:`truncatechars` for
276 277
 more details.
277 278
 
278 279
 ``static`` template tag
279 280
 ~~~~~~~~~~~~~~~~~~~~~~~
280 281
 
281  
-The :mod:`staticfiles<django.contrib.staticfiles>` contrib app has now a new
282  
-:ttag:`static template tag<staticfiles-static>` to refer to files saved with
283  
-the :setting:`STATICFILES_STORAGE` storage backend. It'll use the storage
284  
-``url`` method and therefore supports advanced features such as
  282
+The :mod:`staticfiles<django.contrib.staticfiles>` contrib app has a new
  283
+:ttag:`static<staticfiles-static>` template tag to refer to files saved with
  284
+the :setting:`STATICFILES_STORAGE` storage backend. It uses the storage
  285
+backend's ``url`` method and therefore supports advanced features such as
285 286
 :ref:`serving files from a cloud service<staticfiles-from-cdn>`.
286 287
 
287 288
 ``CachedStaticFilesStorage`` storage backend
288 289
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
289 290
 
290  
-Additional to the `static template tag`_ the
  291
+In addition to the `static template tag`_, the
291 292
 :mod:`staticfiles<django.contrib.staticfiles>` contrib app now has a
292  
-:class:`~django.contrib.staticfiles.storage.CachedStaticFilesStorage` which
293  
-caches the files it saves (when running the :djadmin:`collectstatic`
  293
+:class:`~django.contrib.staticfiles.storage.CachedStaticFilesStorage` backend
  294
+which caches the files it saves (when running the :djadmin:`collectstatic`
294 295
 management command) by appending the MD5 hash of the file's content to the
295 296
 filename. For example, the file ``css/styles.css`` would also be saved as
296 297
 ``css/styles.55e7cbb9ba48.css``
@@ -302,7 +303,7 @@ Simple clickjacking protection
302 303
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
303 304
 
304 305
 We've added a middleware to provide easy protection against `clickjacking
305  
-<http://en.wikipedia.org/wiki/Clickjacking>`_ using the X-Frame-Options
  306
+<http://en.wikipedia.org/wiki/Clickjacking>`_ using the ``X-Frame-Options``
306 307
 header. It's not enabled by default for backwards compatibility reasons, but
307 308
 you'll almost certainly want to :doc:`enable it </ref/clickjacking/>` to help
308 309
 plug that security hole for browsers that support the header.
@@ -312,28 +313,27 @@ CSRF improvements
312 313
 
313 314
 We've made various improvements to our CSRF features, including the
314 315
 :func:`~django.views.decorators.csrf.ensure_csrf_cookie` decorator which can
315  
-help with AJAX heavy sites, protection for PUT and DELETE, and settings
316  
-:setting:`CSRF_COOKIE_SECURE` and :setting:`CSRF_COOKIE_PATH` which can improve
317  
-the security and usefulness of the CSRF protection. See the :doc:`CSRF docs
318  
-</ref/contrib/csrf>` for more information.
  316
+help with AJAX heavy sites, protection for PUT and DELETE requests, and the
  317
+:setting:`CSRF_COOKIE_SECURE` and :setting:`CSRF_COOKIE_PATH` settings which can
  318
+improve the security and usefulness of the CSRF protection. See the :doc:`CSRF
  319
+docs </ref/contrib/csrf>` for more information.
319 320
 
320 321
 Error report filtering
321 322
 ~~~~~~~~~~~~~~~~~~~~~~
322 323
 
323 324
 Two new function decorators, :func:`sensitive_variables` and
324 325
 :func:`sensitive_post_parameters`, were added to allow designating the
325  
-traceback frames' local variables and request's POST parameters susceptible
326  
-to contain sensitive information and that should be filtered out of error
327  
-reports.
  326
+local variables and POST parameters which may contain sensitive
  327
+information and should be filtered out of error reports.
328 328
 
329 329
 All POST parameters are now systematically filtered out of error reports for
330  
-certain :mod:`contrib.views.auth` views (``login``, ``password_reset_confirm``,
331  
-``password_change``, and ``add_view`` and ``user_change_password`` in the
332  
-``auth`` admin) to prevent the leaking of sensitive information such as user
333  
-passwords.
  330
+certain views (``login``, ``password_reset_confirm``, ``password_change``, and
  331
+``add_view`` in :mod:`django.contrib.auth.views`, as well as
  332
+``user_change_password`` in the admin app) to prevent the leaking of sensitive
  333
+information such as user passwords.
334 334
 
335  
-You may override or customize the default filtering by writing a
336  
-:ref:`custom filter<custom-error-reports>`. Learn more on
  335
+You may override or customize the default filtering by writing a :ref:`custom
  336
+filter<custom-error-reports>`. For more information see the docs on
337 337
 :ref:`Filtering error reports<filtering-error-reports>`.
338 338
 
339 339
 Extended IPv6 support
@@ -355,7 +355,7 @@ the previous ``manage.py`` handling of Python import paths that caused double
355 355
 imports, trouble moving from development to deployment, and other
356 356
 difficult-to-debug path issues.
357 357
 
358  
-The previous ``manage.py`` calls functions that are now deprecated, and thus
  358
+The previous ``manage.py`` called functions that are now deprecated, and thus
359 359
 projects upgrading to Django 1.4 should update their ``manage.py``. (The
360 360
 old-style ``manage.py`` will continue to work as before until Django 1.6; in
361 361
 1.5 it will raise ``DeprecationWarning``).
@@ -375,8 +375,8 @@ The new recommended ``manage.py`` file should look like this::
375 375
 ``{{ project_name }}`` should be replaced with the Python package name of the
376 376
 actual project.
377 377
 
378  
-If settings, URLconf, and apps within the project are imported or referenced
379  
-using the project-name prefix (e.g. ``myproject.settings``, ``ROOT_URLCONF =
  378
+If settings, URLconfs, and apps within the project are imported or referenced
  379
+using the project name prefix (e.g. ``myproject.settings``, ``ROOT_URLCONF =
380 380
 "myproject.urls"``, etc), the new ``manage.py`` will need to be moved one
381 381
 directory up, so it is outside the project package rather than adjacent to
382 382
 ``settings.py`` and ``urls.py``.
@@ -433,8 +433,8 @@ Custom project and app templates
433 433
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
434 434
 
435 435
 The :djadmin:`startapp` and :djadmin:`startproject` management commands
436  
-got a ``--template`` option for specifying paths or URL to custom app or
437  
-project templates.
  436
+got a ``--template`` option for specifying a path or URL to a custom app or
  437
+project template.
438 438
 
439 439
 For example, Django will use the ``/path/to/my_project_template``
440 440
 directorywhen running the following command::
@@ -466,7 +466,7 @@ Reasons for using this feature include:
466 466
   timestamps with time zone information in Django 1.3.)
467 467
 - Avoiding data corruption problems around DST transitions.
468 468
 
469  
-Time zone support in enabled by default in new projects created with
  469
+Time zone support is enabled by default in new projects created with
470 470
 :djadmin:`startproject`. If you want to use this feature in an existing
471 471
 project, there is a :ref:`migration guide <time-zones-migration-guide>`.
472 472
 
@@ -487,7 +487,7 @@ Django 1.4 also includes several smaller improvements worth noting:
487 487
 * In the documentation, a helpful :doc:`security overview </topics/security>`
488 488
   page.
489 489
 
490  
-* Function :func:`django.contrib.auth.models.check_password` has been moved
  490
+* The :func:`django.contrib.auth.models.check_password` function has been moved
491 491
   to the :mod:`django.contrib.auth.utils` module. Importing it from the old
492 492
   location will still work, but you should update your imports.
493 493
 
@@ -528,12 +528,13 @@ Django 1.4 also includes several smaller improvements worth noting:
528 528
   ``pickle.HIGHEST_PROTOCOL`` for better compatibility with the other
529 529
   cache backends.
530 530
 
531  
-* Support in the ORM for generating ``SELECT`` queries containing ``DISTINCT ON``
  531
+* Added support in the ORM for generating ``SELECT`` queries containing
  532
+  ``DISTINCT ON``.
532 533
 
533 534
   The ``distinct()`` ``Queryset`` method now accepts an optional list of model
534 535
   field names. If specified, then the ``DISTINCT`` statement is limited to these
535  
-  fields.  The PostgreSQL is the only of the database backends shipped with
536  
-  Django that supports this new functionality.
  536
+  fields. PostgreSQL is the only database backend shipped with Django that
  537
+  supports this new functionality.
537 538
 
538 539
   For more details, see the documentation for
539 540
   :meth:`~django.db.models.query.QuerySet.distinct`.
@@ -550,9 +551,9 @@ stylesheets. Django 1.3 added a new contrib app ``django.contrib.staticfiles``
550 551
 to handle such files in a generic way and defined conventions for static
551 552
 files included in apps.
552 553
 
553  
-Starting in Django 1.4 the admin's static files are now also following this
  554
+Starting in Django 1.4 the admin's static files also follow this
554 555
 convention to make it easier to deploy the included files. In previous
555  
-versions of Django, it was also common to define a ``ADMIN_MEDIA_PREFIX``
  556
+versions of Django, it was also common to define an ``ADMIN_MEDIA_PREFIX``
556 557
 setting to point to the URL where the admin's static files are served by a
557 558
 web server. This setting has now been deprecated and replaced by the more
558 559
 general setting :setting:`STATIC_URL`. Django will now expect to find the
@@ -565,7 +566,7 @@ server continues to serve the admin files just like before. Don't hesitate to
565 566
 consult the :doc:`static files howto </howto/static-files>` for further
566 567
 details.
567 568
 
568  
-In case your ``ADMIN_MEDIA_PREFIX`` is set to an own domain (e.g.
  569
+In case your ``ADMIN_MEDIA_PREFIX`` is set to an specific domain (e.g.
569 570
 ``http://media.example.com/admin/``) make sure to also set your
570 571
 :setting:`STATIC_URL` setting to the correct URL, for example
571 572
 ``http://media.example.com/``.
@@ -601,13 +602,16 @@ As part of an effort to improve the performance and usability of the admin's
601 602
 changelist sorting interface and of the admin's :attr:`horizontal
602 603
 <django.contrib.admin.ModelAdmin.filter_horizontal>` and :attr:`vertical
603 604
 <django.contrib.admin.ModelAdmin.filter_vertical>` "filter" widgets, some icon
604  
-files were removed and grouped into two sprite files, respectively:
605  
-``selector-add.gif``, ``selector-addall.gif``, ``selector-remove.gif``,
606  
-``selector-removeall.gif``, ``selector_stacked-add.gif`` and
607  
-``selector_stacked-remove.gif`` into ``selector-icons.gif``; and
608  
-``arrow-up.gif`` and ``arrow-down.gif`` into ``sorting-icons.gif``. If you used
609  
-those icons to customize the admin then you will want to replace them with your
610  
-own icons or retrieve them from a previous release.
  605
+files were removed and grouped into two sprite files.
  606
+
  607
+Specifically: ``selector-add.gif``, ``selector-addall.gif``,
  608
+``selector-remove.gif``, ``selector-removeall.gif``,
  609
+``selector_stacked-add.gif`` and ``selector_stacked-remove.gif`` were
  610
+combined into ``selector-icons.gif``; and ``arrow-up.gif`` and
  611
+``arrow-down.gif`` were combined into ``sorting-icons.gif``.
  612
+
  613
+If you used those icons to customize the admin then you will want to replace
  614
+them with your own icons or retrieve them from a previous release.
611 615
 
612 616
 CSS class names in admin forms
613 617
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -628,39 +632,39 @@ produced by the previous methods, these fallbacks are removed in Django 1.4.
628 632
 
629 633
 So, if you upgrade to Django 1.4 directly from 1.2 or earlier, you may
630 634
 lose/invalidate certain pieces of data that have been cryptographically signed
631  
-using an old method. To avoid this, use Django 1.3 first, for a period of time,
  635
+using an old method. To avoid this, use Django 1.3 first for a period of time
632 636
 to allow the signed data to expire naturally. The affected parts are detailed
633 637
 below, with 1) the consequences of ignoring this advice and 2) the amount of
634 638
 time you need to run Django 1.3 for the data to expire or become irrelevant.
635 639
 
636  
-* contrib.sessions data integrity check
  640
+* ``contrib.sessions`` data integrity check
637 641
 
638 642
   * consequences: the user will be logged out, and session data will be lost.
639 643
 
640  
-  * time period: defined by SESSION_COOKIE_AGE.
  644
+  * time period: defined by :setting:`SESSION_COOKIE_AGE`.
641 645
 
642  
-* contrib.auth password reset hash
  646
+* ``contrib.auth`` password reset hash
643 647
 
644 648
   * consequences: password reset links from before the upgrade will not work.
645 649
 
646  
-  * time period: defined by PASSWORD_RESET_TIMEOUT_DAYS.
  650
+  * time period: defined by :setting:`PASSWORD_RESET_TIMEOUT_DAYS`.
647 651
 
648  
-Form related hashes — these are much shorter lifetime, and are relevant only for
  652
+Form-related hashes — these are much shorter lifetime, and are relevant only for
649 653
 the short window where a user might fill in a form generated by the pre-upgrade
650 654
 Django instance, and try to submit it to the upgraded Django instance:
651 655
 
652  
-* contrib.comments form security hash
  656
+* ``contrib.comments`` form security hash
653 657
 
654 658
   * consequences: the user will see a validation error "Security hash failed".
655 659
 
656 660
   * time period: the amount of time you expect users to take filling out comment
657 661
     forms.
658 662
 
659  
-* FormWizard security hash
  663
+* ``FormWizard`` security hash
660 664
 
661 665
   * consequences: the user will see an error about the form having expired,
662 666
     and will be sent back to the first page of the wizard, losing the data
663  
-    they have inputted so far.
  667
+    they have entered so far.
664 668
 
665 669
   * time period: the amount of time you expect users to take filling out the
666 670
     affected forms.
@@ -702,9 +706,9 @@ specification, some changes were made to the JSON serializer:
702 706
   only supports milliseconds (3 digits). However, it's better than discarding
703 707
   microseconds entirely.
704 708
 
705  
-The XML serializer was also changed to use ISO8601 for datetimes. The letter
706  
-``T`` is used to separate the date part from the time part, instead of a
707  
-space. Time zone information is included in the ``[+-]HH:MM`` format.
  709
+The XML serializer was also changed to use the ISO8601 format for datetimes.
  710
+The letter ``T`` is used to separate the date part from the time part, instead
  711
+of a space. Time zone information is included in the ``[+-]HH:MM`` format.
708 712
 
709 713
 The serializers will dump datetimes in fixtures with these new formats. They
710 714
 can still load fixtures that use the old format.
@@ -733,7 +737,7 @@ global, the ``django.db.connections`` dictionary referencing those objects is
733 737
 still thread-local. Therefore if you just use the ORM or
734 738
 ``DatabaseWrapper.cursor()`` then the behavior is still the same as before.
735 739
 Note, however, that ``django.db.connection`` does not directly reference the
736  
-default ``DatabaseWrapper`` object any more and is now a proxy to access that
  740
+default ``DatabaseWrapper`` object anymore and is now a proxy to access that
737 741
 object's attributes. If you need to access the actual ``DatabaseWrapper``
738 742
 object, use ``django.db.connections[DEFAULT_DB_ALIAS]`` instead.
739 743
 
@@ -754,7 +758,7 @@ Check their documentation for details.
754 758
 Django's :doc:`comments app </ref/contrib/comments/index>` has historically
755 759
 supported excluding the comments of a special user group, but we've never
756 760
 documented the feature properly and didn't enforce the exclusion in other parts
757  
-of the app, e.g., the template tags. To fix this problem, we removed the code
  761
+of the app such as the template tags. To fix this problem, we removed the code
758 762
 from the feed class.
759 763
 
760 764
 If you rely on the feature and want to restore the old behavior, simply use
@@ -792,10 +796,9 @@ For more details, see the documentation about
792 796
 `IGNORABLE_404_STARTS` and `IGNORABLE_404_ENDS` settings
793 797
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
794 798
 
795  
-Django can report 404 errors: see :doc:`/howto/error-reporting`.
796  
-Until Django 1.3, it was possible to exclude some URLs from the reporting
797  
-by adding prefixes to :setting:`IGNORABLE_404_STARTS` and suffixes to
798  
-:setting:`IGNORABLE_404_ENDS`.
  799
+Until Django 1.3, it was possible to exclude some URLs from Django's
  800
+:doc:`404 error reporting</howto/error-reporting>` by adding prefixes to
  801
+:setting:`IGNORABLE_404_STARTS` and suffixes to :setting:`IGNORABLE_404_ENDS`.
799 802
 
800 803
 In Django 1.4, these two settings are superseded by
801 804
 :setting:`IGNORABLE_404_URLS`, which is a list of compiled regular expressions.
@@ -905,7 +908,7 @@ Support for PostgreSQL versions older than 8.2
905 908
 Django 1.3 dropped support for PostgreSQL versions older than 8.0 and the
906 909
 relevant documents suggested to use a recent version because of performance
907 910
 reasons but more importantly because end of the upstream support periods for
908  
-releases 8.0 and 8.1 was near (November 2010.)
  911
+releases 8.0 and 8.1 was near (November 2010).
909 912
 
910 913
 Django 1.4 takes that policy further and sets 8.2 as the minimum PostgreSQL
911 914
 version it officially supports.
@@ -918,13 +921,13 @@ admin error email support was moved into the
918 921
 :class:`django.utils.log.AdminEmailHandler`, attached to the
919 922
 ``'django.request'`` logger. In order to maintain the established behavior of
920 923
 error emails, the ``'django.request'`` logger was called only when
921  
-:setting:`DEBUG` was `False`.
  924
+:setting:`DEBUG` was ``False``.
922 925
 
923  
-To increase the flexibility of request-error logging, the ``'django.request'``
924  
-logger is now called regardless of the value of :setting:`DEBUG`, and the
925  
-default settings file for new projects now includes a separate filter attached
926  
-to :class:`django.utils.log.AdminEmailHandler` to prevent admin error emails in
927  
-`DEBUG` mode::
  926
+To increase the flexibility of error logging for requests, the
  927
+``'django.request'`` logger is now called regardless of the value of
  928
+:setting:`DEBUG`, and the default settings file for new projects now includes a
  929
+separate filter attached to :class:`django.utils.log.AdminEmailHandler` to
  930
+prevent admin error emails in ``DEBUG`` mode::
928 931
 
929 932
    'filters': {
930 933
         'require_debug_false': {
@@ -963,13 +966,13 @@ Starting with Django 1.4 they are now available in :mod:`django.conf.urls`.
963 966
 ``django.contrib.databrowse``
964 967
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
965 968
 
966  
-Databrowse has not seen active development for some time, and this does not
967  
-show any sign of changing. There had been a suggestion for a GSOC project to
  969
+Databrowse has not seen active development for some time, and this does not show
  970
+any sign of changing. There had been a suggestion for a `GSOC project`_ to
968 971
 integrate the functionality of databrowse into the admin, but no progress was
969 972
 made. While Databrowse has been deprecated, an enhancement of
970  
-django.contrib.admin providing a similar feature set is still possible.
  973
+``django.contrib.admin`` providing a similar feature set is still possible.
971 974
 
972  
-.. _GSOC Proposal: https://code.djangoproject.com/wiki/SummerOfCode2011#Integratedatabrowseintotheadmin
  975
+.. _GSOC project: https://code.djangoproject.com/wiki/SummerOfCode2011#Integratedatabrowseintotheadmin
973 976
 
974 977
 The code that powers Databrowse is licensed under the same terms as Django
975 978
 itself, and so is available to be adopted by an individual or group as
@@ -983,10 +986,10 @@ This function temporarily modified ``sys.path`` in order to make the parent
983 986
 layout. This function is now deprecated, as its path workarounds are no longer
984 987
 needed with the new ``manage.py`` and default project layout.
985 988
 
986  
-This function was never documented or public API, but was widely recommended
987  
-for use in setting up a "Django environment" for a user script. These uses
988  
-should be replaced by setting the ``DJANGO_SETTINGS_MODULE`` environment
989  
-variable or using :func:`django.conf.settings.configure`.
  989
+This function was never documented or part of the public API, but was widely
  990
+recommended for use in setting up a "Django environment" for a user script.
  991
+These uses should be replaced by setting the ``DJANGO_SETTINGS_MODULE``
  992
+environment variable or using :func:`django.conf.settings.configure`.
990 993
 
991 994
 ``django.core.management.execute_manager``
992 995
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -994,10 +997,10 @@ variable or using :func:`django.conf.settings.configure`.
994 997
 This function was previously used by ``manage.py`` to execute a management
995 998
 command. It is identical to
996 999
 ``django.core.management.execute_from_command_line``, except that it first
997  
-calls ``setup_environ``, which is now deprecated. ``execute_manager`` is also
998  
-deprecated; ``execute_from_command_line`` can be used instead. (Neither of
999  
-these functions is documented public API, but a deprecation path is needed due
1000  
-to use in existing ``manage.py`` files.)
  1000
+calls ``setup_environ``, which is now deprecated. As such, ``execute_manager``
  1001
+is also deprecated; ``execute_from_command_line`` can be used instead. Neither
  1002
+of these functions is documented as part of the public API, but a deprecation
  1003
+path is needed due to use in existing ``manage.py`` files.
1001 1004
 
1002 1005
 ``is_safe`` and ``needs_autoescape`` attributes of template filters
1003 1006
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1027,7 +1030,7 @@ Session cookies now have the ``httponly`` flag by default
1027 1030
 
1028 1031
 Session cookies now include the ``httponly`` attribute by default to
1029 1032
 help reduce the impact of potential XSS attacks. For strict backwards
1030  
-compatibility, use ``SESSION_COOKIE_HTTPONLY = False`` in settings.
  1033
+compatibility, use ``SESSION_COOKIE_HTTPONLY = False`` in your settings file.
1031 1034
 
1032 1035
 Wildcard expansion of application names in `INSTALLED_APPS`
1033 1036
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
265  docs/releases/1.4.txt
@@ -41,7 +41,7 @@ What's new in Django 1.4
41 41
 Support for in-browser testing frameworks
42 42
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
43 43
 
44  
-Django 1.4 now supports the integration with in-browser testing frameworks such
  44
+Django 1.4 now supports integration with in-browser testing frameworks such
45 45
 as Selenium_ or Windmill_ thanks to the :class:`django.test.LiveServerTestCase`
46 46
 base class, allowing you to test the interactions between your site's front and
47 47
 back ends more comprehensively. See the
@@ -81,56 +81,55 @@ Similar to :meth:`~django.db.models.query.QuerySet.select_related` but with a
81 81
 different strategy and broader scope,
82 82
 :meth:`~django.db.models.query.QuerySet.prefetch_related` has been added to
83 83
 :class:`~django.db.models.query.QuerySet`. This method returns a new
84  
-``QuerySet`` that will prefetch in a single batch each of the specified related
85  
-lookups as soon as it begins to be evaluated. Unlike ``select_related``, it does
86  
-the joins in Python, not in the database, and supports many-to-many
87  
-relationships, :class:`~django.contrib.contenttypes.generic.GenericForeignKey`
88  
-and more. This enables you to fix many instances of a very common performance
89  
-problem, in which your code ends up doing O(n) database queries (or worse) if
90  
-objects on your primary ``QuerySet`` each have many related objects that you
91  
-also need.
92  
-
93  
-HTML5
94  
-~~~~~
  84
+``QuerySet`` that will prefetch each of the specified related lookups in a
  85
+single batch as soon as the query begins to be evaluated. Unlike
  86
+``select_related``, it does the joins in Python, not in the database, and
  87
+supports many-to-many relationships,
  88
+:class:`~django.contrib.contenttypes.generic.GenericForeignKey` and more. This
  89
+allows you to fix a very common performance problem in which your code ends up
  90
+doing O(n) database queries (or worse) if objects on your primary ``QuerySet``
  91
+each have many related objects that you also need.
  92
+
  93
+HTML5 Doctype
  94
+~~~~~~~~~~~~~
95 95
 
96 96
 We've switched the admin and other bundled templates to use the HTML5
97  
-doctype. While Django will be careful in its use of HTML5 features, to maintain
98  
-compatibility with older browsers, this change means that you can use any HTML5
99  
-features you need in admin pages without having to lose HTML validity or
100  
-override the provided templates to change the doctype.
  97
+doctype. While Django will be careful to maintain compatibility with older
  98
+browsers, this change means that you can use any HTML5 features you need in
  99
+admin pages without having to lose HTML validity or override the provided
  100
+templates to change the doctype.
101 101
 
102 102
 List filters in admin interface
103 103
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
104 104
 
105  
-Prior to Django 1.4, the Django admin app allowed specifying change list
106  
-filters by specifying a field lookup (including spanning relations), and
107  
-not custom filters. This has been rectified with a simple API previously
108  
-known as "FilterSpec" which was used internally. For more details, see the
109  
-documentation for :attr:`~django.contrib.admin.ModelAdmin.list_filter`.
  105
+Prior to Django 1.4, the :mod:`~django.contrib.admin` app allowed you to specify
  106
+change list filters by specifying a field lookup, but didn't allow you to create
  107
+custom filters. This has been rectified with a simple API (previously used
  108
+internally and known as "FilterSpec"). For more details, see the documentation
  109
+for :attr:`~django.contrib.admin.ModelAdmin.list_filter`.
110 110
 
111 111
 Multiple sort in admin interface
112 112
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
113 113
 
114  
-The admin change list now supports sorting on multiple columns. It respects
115  
-all elements of the :attr:`~django.contrib.admin.ModelAdmin.ordering`
116  
-attribute, and sorting on multiple columns by clicking on headers is designed
117  
-to work similarly to how desktop GUIs do it. The new hook
118  
-:meth:`~django.contrib.admin.ModelAdmin.get_ordering` for specifying the
  114
+The admin change list now supports sorting on multiple columns. It respects all
  115
+elements of the :attr:`~django.contrib.admin.ModelAdmin.ordering` attribute, and
  116
+sorting on multiple columns by clicking on headers is designed to mimic the
  117
+behavior of desktop GUIs. The
  118
+:meth:`~django.contrib.admin.ModelAdmin.get_ordering` method for specifying the
119 119
 ordering dynamically (e.g. depending on the request) has also been added.
120 120
 
121 121
 New ``ModelAdmin`` methods
122 122
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
123 123
 
124 124
 A new :meth:`~django.contrib.admin.ModelAdmin.save_related` method was added to
125  
-:mod:`~django.contrib.admin.ModelAdmin` to ease the customization of how
  125
+:mod:`~django.contrib.admin.ModelAdmin` to ease customization of how
126 126
 related objects are saved in the admin.
127 127
 
128 128
 Two other new methods,
129 129
 :meth:`~django.contrib.admin.ModelAdmin.get_list_display` and
130 130
 :meth:`~django.contrib.admin.ModelAdmin.get_list_display_links`
131 131
 were added to :class:`~django.contrib.admin.ModelAdmin` to enable the dynamic
132  
-customization of fields and links to display on the admin
133  
-change list.
  132
+customization of fields and links displayed on the admin change list.
134 133
 
135 134
 Admin inlines respect user permissions
136 135
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -148,30 +147,31 @@ Django 1.4 adds both a low-level API for signing values and a high-level API
148 147
 for setting and reading signed cookies, one of the most common uses of
149 148
 signing in Web applications.
150 149
 
151  
-See :doc:`cryptographic signing </topics/signing>` docs for more information.
  150
+See the :doc:`cryptographic signing </topics/signing>` docs for more
  151
+information.
152 152
 
153 153
 Cookie-based session backend
154 154
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
155 155
 
156  
-Django 1.4 introduces a new cookie based backend for the session framework
  156
+Django 1.4 introduces a new cookie-based backend for the session framework
157 157
 which uses the tools for :doc:`cryptographic signing </topics/signing>` to
158 158
 store the session data in the client's browser.
159 159
 
160  
-See the :ref:`cookie-based backend <cookie-session-backend>` docs for
  160
+See the :ref:`cookie-based session backend <cookie-session-backend>` docs for
161 161
 more information.
162 162
 
163 163
 New form wizard
164 164
 ~~~~~~~~~~~~~~~
165 165
 
166  
-The previously shipped ``FormWizard`` of the formtools contrib app has been
167  
-replaced with a new implementation that is based on the class based views
  166
+The previous ``FormWizard`` from the formtools contrib app has been
  167
+replaced with a new implementation based on the class-based views
168 168
 introduced in Django 1.3. It features a pluggable storage API and doesn't
169 169
 require the wizard to pass around hidden fields for every previous step.
170 170
 
171  
-Django 1.4 ships with a session based storage backend and a cookie based
  171
+Django 1.4 ships with a session-based storage backend and a cookie-based
172 172
 storage backend. The latter uses the tools for
173 173
 :doc:`cryptographic signing </topics/signing>` also introduced in
174  
-Django 1.4 to store the wizard state in the user's cookies.
  174
+Django 1.4 to store the wizard's state in the user's cookies.
175 175
 
176 176
 See the :doc:`form wizard </ref/contrib/formtools/form-wizard>` docs for
177 177
 more information.
@@ -186,7 +186,7 @@ Translating URL patterns
186 186
 ~~~~~~~~~~~~~~~~~~~~~~~~
187 187
 
188 188
 Django 1.4 gained the ability to look for a language prefix in the URL pattern
189  
-when using the new :func:`django.conf.urls.i18n.i18n_patterns` helper function.
  189
+when using the new :func:`~django.conf.urls.i18n.i18n_patterns` helper function.
190 190
 Additionally, it's now possible to define translatable URL patterns using
191 191
 :func:`~django.utils.translation.ugettext_lazy`. See
192 192
 :ref:`url-internationalization` for more information about the language prefix
@@ -195,34 +195,35 @@ and how to internationalize URL patterns.
195 195
 Contextual translation support for ``{% trans %}`` and ``{% blocktrans %}``
196 196
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
197 197
 
198  
-Django 1.3 introduced :ref:`contextual translation<contextual-markers>` support
199  
-in Python files via the ``pgettext`` function. This is now also supported by
200  
-the :ttag:`trans` and :ttag:`blocktrans` template tags using the new
201  
-``context`` keyword.
  198
+The :ref:`contextual translation<contextual-markers>` support introduced in
  199
+Django 1.3 via the ``pgettext`` function has been extended to the
  200
+:ttag:`trans` and :ttag:`blocktrans` template tags using the new ``context``
  201
+keyword.
202 202
 
203 203
 Customizable ``SingleObjectMixin`` URLConf kwargs
204 204
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
205 205
 
206 206
 Two new attributes,
207  
-:attr:`pk_url_kwarg<django.views.generic.detail.SingleObjectMixin.pk_url_kwarg>` and
  207
+:attr:`pk_url_kwarg<django.views.generic.detail.SingleObjectMixin.pk_url_kwarg>`
  208
+and
208 209
 :attr:`slug_url_kwarg<django.views.generic.detail.SingleObjectMixin.slug_url_kwarg>`,
209  
-have been added to :class:`django.views.generic.detail.SingleObjectMixin` to
  210
+have been added to :class:`~django.views.generic.detail.SingleObjectMixin` to
210 211
 enable the customization of URLConf keyword arguments used for single
211 212
 object generic views.
212 213
 
213 214
 Assignment template tags
214 215
 ~~~~~~~~~~~~~~~~~~~~~~~~
215 216
 
216  
-A new helper function,
217  
-:ref:`assignment_tag<howto-custom-template-tags-assignment-tags>`, was added to
218  
-``template.Library`` to ease the creation of template tags that store some
219  
-data in a specified context variable.
  217
+A new :ref:`assignment_tag<howto-custom-template-tags-assignment-tags>` helper
  218
+function was added to ``template.Library`` to ease the creation of template
  219
+tags that store data in a specified context variable.
220 220
 
221 221
 ``*args`` and ``**kwargs`` support for template tag helper functions
222 222
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
223 223
 
224  
-:ref:`simple_tag<howto-custom-template-tags-simple-tags>`, :ref:`inclusion_tag
225  
-<howto-custom-template-tags-inclusion-tags>` and the newly introduced
  224
+The :ref:`simple_tag<howto-custom-template-tags-simple-tags>`,
  225
+:ref:`inclusion_tag <howto-custom-template-tags-inclusion-tags>` and
  226
+newly introduced
226 227
 :ref:`assignment_tag<howto-custom-template-tags-assignment-tags>` template
227 228
 helper functions may now accept any number of positional or keyword arguments.
228 229
 For example:
@@ -263,25 +264,25 @@ exceptions from template rendering is now consistent regardless of the value of
263 264
 
264 265
 Added a filter which truncates a string to be no longer than the specified
265 266
 number of characters. Truncated strings end with a translatable ellipsis
266  
-sequence ("..."). See the :tfilter:`truncatechars docs <truncatechars>` for
  267
+sequence ("..."). See the documentation for :tfilter:`truncatechars` for
267 268
 more details.
268 269
 
269 270
 ``static`` template tag
270 271
 ~~~~~~~~~~~~~~~~~~~~~~~
271 272
 
272  
-The :mod:`staticfiles<django.contrib.staticfiles>` contrib app has now a new
273  
-:ttag:`static template tag<staticfiles-static>` to refer to files saved with
274  
-the :setting:`STATICFILES_STORAGE` storage backend. It'll use the storage
275  
-``url`` method and therefore supports advanced features such as
  273
+The :mod:`staticfiles<django.contrib.staticfiles>` contrib app has a new
  274
+:ttag:`static<staticfiles-static>` template tag to refer to files saved with
  275
+the :setting:`STATICFILES_STORAGE` storage backend. It uses the storage
  276
+backend's ``url`` method and therefore supports advanced features such as
276 277
 :ref:`serving files from a cloud service<staticfiles-from-cdn>`.
277 278
 
278 279
 ``CachedStaticFilesStorage`` storage backend
279 280
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
280 281
 
281  
-Additional to the `static template tag`_ the
  282
+In addition to the `static template tag`_, the
282 283
 :mod:`staticfiles<django.contrib.staticfiles>` contrib app now has a
283  
-:class:`~django.contrib.staticfiles.storage.CachedStaticFilesStorage` which
284  
-caches the files it saves (when running the :djadmin:`collectstatic`
  284
+:class:`~django.contrib.staticfiles.storage.CachedStaticFilesStorage` backend
  285
+which caches the files it saves (when running the :djadmin:`collectstatic`
285 286
 management command) by appending the MD5 hash of the file's content to the
286 287
 filename. For example, the file ``css/styles.css`` would also be saved as
287 288
 ``css/styles.55e7cbb9ba48.css``
@@ -293,7 +294,7 @@ Simple clickjacking protection
293 294
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
294 295
 
295 296
 We've added a middleware to provide easy protection against `clickjacking
296  
-<http://en.wikipedia.org/wiki/Clickjacking>`_ using the X-Frame-Options
  297
+<http://en.wikipedia.org/wiki/Clickjacking>`_ using the ``X-Frame-Options``
297 298
 header. It's not enabled by default for backwards compatibility reasons, but
298 299
 you'll almost certainly want to :doc:`enable it </ref/clickjacking/>` to help
299 300
 plug that security hole for browsers that support the header.
@@ -303,28 +304,27 @@ CSRF improvements
303 304
 
304 305
 We've made various improvements to our CSRF features, including the
305 306
 :func:`~django.views.decorators.csrf.ensure_csrf_cookie` decorator which can
306  
-help with AJAX heavy sites, protection for PUT and DELETE, and settings
307  
-:setting:`CSRF_COOKIE_SECURE` and :setting:`CSRF_COOKIE_PATH` which can improve
308  
-the security and usefulness of the CSRF protection. See the :doc:`CSRF docs
309  
-</ref/contrib/csrf>` for more information.
  307
+help with AJAX heavy sites, protection for PUT and DELETE requests, and the
  308
+:setting:`CSRF_COOKIE_SECURE` and :setting:`CSRF_COOKIE_PATH` settings which can
  309
+improve the security and usefulness of the CSRF protection. See the :doc:`CSRF
  310
+docs </ref/contrib/csrf>` for more information.
310 311
 
311 312
 Error report filtering
312 313
 ~~~~~~~~~~~~~~~~~~~~~~
313 314
 
314 315
 Two new function decorators, :func:`sensitive_variables` and
315 316
 :func:`sensitive_post_parameters`, were added to allow designating the
316  
-traceback frames' local variables and request's POST parameters susceptible
317  
-to contain sensitive information and that should be filtered out of error
318  
-reports.
  317
+local variables and POST parameters which may contain sensitive
  318
+information and should be filtered out of error reports.
319 319
 
320 320
 All POST parameters are now systematically filtered out of error reports for
321  
-certain :mod:`contrib.views.auth` views (``login``, ``password_reset_confirm``,
322  
-``password_change``, and ``add_view`` and ``user_change_password`` in the
323  
-``auth`` admin) to prevent the leaking of sensitive information such as user
324  
-passwords.
  321
+certain views (``login``, ``password_reset_confirm``, ``password_change``, and
  322
+``add_view`` in :mod:`django.contrib.auth.views`, as well as
  323
+``user_change_password`` in the admin app) to prevent the leaking of sensitive
  324
+information such as user passwords.
325 325
 
326  
-You may override or customize the default filtering by writing a
327  
-:ref:`custom filter<custom-error-reports>`. Learn more on
  326
+You may override or customize the default filtering by writing a :ref:`custom
  327
+filter<custom-error-reports>`. For more information see the docs on
328 328
 :ref:`Filtering error reports<filtering-error-reports>`.
329 329
 
330 330
 Extended IPv6 support
@@ -346,7 +346,7 @@ the previous ``manage.py`` handling of Python import paths that caused double
346 346
 imports, trouble moving from development to deployment, and other
347 347
 difficult-to-debug path issues.
348 348
 
349  
-The previous ``manage.py`` calls functions that are now deprecated, and thus
  349
+The previous ``manage.py`` called functions that are now deprecated, and thus
350 350
 projects upgrading to Django 1.4 should update their ``manage.py``. (The
351 351
 old-style ``manage.py`` will continue to work as before until Django 1.6; in
352 352
 1.5 it will raise ``DeprecationWarning``).
@@ -366,8 +366,8 @@ The new recommended ``manage.py`` file should look like this::
366 366
 ``{{ project_name }}`` should be replaced with the Python package name of the
367 367
 actual project.
368 368
 
369  
-If settings, URLconf, and apps within the project are imported or referenced
370  
-using the project-name prefix (e.g. ``myproject.settings``, ``ROOT_URLCONF =
  369
+If settings, URLconfs, and apps within the project are imported or referenced
  370
+using the project name prefix (e.g. ``myproject.settings``, ``ROOT_URLCONF =
371 371
 "myproject.urls"``, etc), the new ``manage.py`` will need to be moved one
372 372
 directory up, so it is outside the project package rather than adjacent to
373 373
 ``settings.py`` and ``urls.py``.
@@ -424,8 +424,8 @@ Custom project and app templates
424 424
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
425 425
 
426 426
 The :djadmin:`startapp` and :djadmin:`startproject` management commands
427  
-got a ``--template`` option for specifying paths or URL to custom app or
428  
-project templates.
  427
+got a ``--template`` option for specifying a path or URL to a custom app or
  428
+project template.
429 429
 
430 430
 For example, Django will use the ``/path/to/my_project_template``
431 431
 directorywhen running the following command::
@@ -457,7 +457,7 @@ Reasons for using this feature include:
457 457
   timestamps with time zone information in Django 1.3.)
458 458
 - Avoiding data corruption problems around DST transitions.
459 459
 
460  
-Time zone support in enabled by default in new projects created with
  460
+Time zone support is enabled by default in new projects created with
461 461
 :djadmin:`startproject`. If you want to use this feature in an existing
462 462
 project, there is a :ref:`migration guide <time-zones-migration-guide>`.
463 463
 
@@ -478,7 +478,7 @@ Django 1.4 also includes several smaller improvements worth noting:
478 478
 * In the documentation, a helpful :doc:`security overview </topics/security>`
479 479
   page.
480 480
 
481  
-* Function :func:`django.contrib.auth.models.check_password` has been moved
  481
+* The :func:`django.contrib.auth.models.check_password` function has been moved
482 482
   to the :mod:`django.contrib.auth.utils` module. Importing it from the old
483 483
   location will still work, but you should update your imports.
484 484
 
@@ -519,18 +519,17 @@ Django 1.4 also includes several smaller improvements worth noting:
519 519
   ``pickle.HIGHEST_PROTOCOL`` for better compatibility with the other
520 520
   cache backends.
521 521
 
522  
-* Support in the ORM for generating ``SELECT`` queries containing ``DISTINCT ON``
  522
+* Added support in the ORM for generating ``SELECT`` queries containing
  523
+  ``DISTINCT ON``.
523 524
 
524 525
   The ``distinct()`` ``Queryset`` method now accepts an optional list of model
525 526
   field names. If specified, then the ``DISTINCT`` statement is limited to these
526  
-  fields.  The PostgreSQL is the only of the database backends shipped with
527  
-  Django that supports this new functionality.
  527
+  fields. PostgreSQL is the only database backend shipped with Django that
  528
+  supports this new functionality.
528 529
 
529 530
   For more details, see the documentation for
530 531
   :meth:`~django.db.models.query.QuerySet.distinct`.
531 532
 
532  
-.. _backwards-incompatible-changes-1.4:
533  
-
534 533
 Backwards incompatible changes in 1.4
535 534
 =====================================
536 535
 
@@ -543,9 +542,9 @@ stylesheets. Django 1.3 added a new contrib app ``django.contrib.staticfiles``
543 542
 to handle such files in a generic way and defined conventions for static
544 543
 files included in apps.
545 544
 
546  
-Starting in Django 1.4 the admin's static files are now also following this
  545
+Starting in Django 1.4 the admin's static files also follow this
547 546
 convention to make it easier to deploy the included files. In previous
548  
-versions of Django, it was also common to define a ``ADMIN_MEDIA_PREFIX``
  547
+versions of Django, it was also common to define an ``ADMIN_MEDIA_PREFIX``
549 548
 setting to point to the URL where the admin's static files are served by a
550 549
 web server. This setting has now been deprecated and replaced by the more
551 550
 general setting :setting:`STATIC_URL`. Django will now expect to find the
@@ -558,7 +557,7 @@ server continues to serve the admin files just like before. Don't hesitate to
558 557
 consult the :doc:`static files howto </howto/static-files>` for further
559 558
 details.
560 559
 
561  
-In case your ``ADMIN_MEDIA_PREFIX`` is set to an own domain (e.g.
  560
+In case your ``ADMIN_MEDIA_PREFIX`` is set to an specific domain (e.g.
562 561
 ``http://media.example.com/admin/``) make sure to also set your
563 562
 :setting:`STATIC_URL` setting to the correct URL, for example
564 563
 ``http://media.example.com/``.
@@ -594,13 +593,16 @@ As part of an effort to improve the performance and usability of the admin's
594 593
 changelist sorting interface and of the admin's :attr:`horizontal
595 594
 <django.contrib.admin.ModelAdmin.filter_horizontal>` and :attr:`vertical
596 595
 <django.contrib.admin.ModelAdmin.filter_vertical>` "filter" widgets, some icon
597  
-files were removed and grouped into two sprite files, respectively:
598  
-``selector-add.gif``, ``selector-addall.gif``, ``selector-remove.gif``,
599  
-``selector-removeall.gif``, ``selector_stacked-add.gif`` and
600  
-``selector_stacked-remove.gif`` into ``selector-icons.gif``; and
601  
-``arrow-up.gif`` and ``arrow-down.gif`` into ``sorting-icons.gif``. If you used
602  
-those icons to customize the admin then you will want to replace them with your
603  
-own icons or retrieve them from a previous release.
  596
+files were removed and grouped into two sprite files.
  597
+
  598
+Specifically: ``selector-add.gif``, ``selector-addall.gif``,
  599
+``selector-remove.gif``, ``selector-removeall.gif``,
  600
+``selector_stacked-add.gif`` and ``selector_stacked-remove.gif`` were
  601
+combined into ``selector-icons.gif``; and ``arrow-up.gif`` and
  602
+``arrow-down.gif`` were combined into ``sorting-icons.gif``.
  603
+
  604
+If you used those icons to customize the admin then you will want to replace
  605
+them with your own icons or retrieve them from a previous release.
604 606
 
605 607
 CSS class names in admin forms
606 608
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -621,39 +623,39 @@ produced by the previous methods, these fallbacks are removed in Django 1.4.
621 623
 
622 624
 So, if you upgrade to Django 1.4 directly from 1.2 or earlier, you may
623 625
 lose/invalidate certain pieces of data that have been cryptographically signed
624  
-using an old method. To avoid this, use Django 1.3 first, for a period of time,
  626
+using an old method. To avoid this, use Django 1.3 first for a period of time
625 627
 to allow the signed data to expire naturally. The affected parts are detailed
626 628
 below, with 1) the consequences of ignoring this advice and 2) the amount of
627 629
 time you need to run Django 1.3 for the data to expire or become irrelevant.
628 630
 
629  
-* contrib.sessions data integrity check
  631
+* ``contrib.sessions`` data integrity check
630 632
 
631 633
   * consequences: the user will be logged out, and session data will be lost.
632 634
 
633  
-  * time period: defined by SESSION_COOKIE_AGE.
  635
+  * time period: defined by :setting:`SESSION_COOKIE_AGE`.
634 636
 
635  
-* contrib.auth password reset hash
  637
+* ``contrib.auth`` password reset hash
636 638
 
637 639
   * consequences: password reset links from before the upgrade will not work.
638 640
 
639  
-  * time period: defined by PASSWORD_RESET_TIMEOUT_DAYS.
  641
+  * time period: defined by :setting:`PASSWORD_RESET_TIMEOUT_DAYS`.
640 642
 
641  
-Form related hashes — these are much shorter lifetime, and are relevant only for
  643
+Form-related hashes — these are much shorter lifetime, and are relevant only for
642 644
 the short window where a user might fill in a form generated by the pre-upgrade
643 645
 Django instance, and try to submit it to the upgraded Django instance:
644 646
 
645  
-* contrib.comments form security hash
  647
+* ``contrib.comments`` form security hash
646 648
 
647 649
   * consequences: the user will see a validation error "Security hash failed".
648 650
 
649 651
   * time period: the amount of time you expect users to take filling out comment
650 652
     forms.
651 653
 
652  
-* FormWizard security hash
  654
+* ``FormWizard`` security hash
653 655
 
654 656
   * consequences: the user will see an error about the form having expired,
655 657
     and will be sent back to the first page of the wizard, losing the data
656  
-    they have inputted so far.
  658
+    they have entered so far.
657 659
 
658 660
   * time period: the amount of time you expect users to take filling out the
659 661
     affected forms.
@@ -695,9 +697,9 @@ specification, some changes were made to the JSON serializer:
695 697
   only supports milliseconds (3 digits). However, it's better than discarding
696 698
   microseconds entirely.
697 699
 
698  
-The XML serializer was also changed to use ISO8601 for datetimes. The letter
699  
-``T`` is used to separate the date part from the time part, instead of a
700  
-space. Time zone information is included in the ``[+-]HH:MM`` format.
  700
+The XML serializer was also changed to use the ISO8601 format for datetimes.
  701
+The letter ``T`` is used to separate the date part from the time part, instead
  702
+of a space. Time zone information is included in the ``[+-]HH:MM`` format.
701 703
 
702 704
 The serializers will dump datetimes in fixtures with these new formats. They
703 705
 can still load fixtures that use the old format.
@@ -726,7 +728,7 @@ global, the ``django.db.connections`` dictionary referencing those objects is
726 728
 still thread-local. Therefore if you just use the ORM or
727 729
 ``DatabaseWrapper.cursor()`` then the behavior is still the same as before.
728 730
 Note, however, that ``django.db.connection`` does not directly reference the
729  
-default ``DatabaseWrapper`` object any more and is now a proxy to access that
  731
+default ``DatabaseWrapper`` object anymore and is now a proxy to access that
730 732
 object's attributes. If you need to access the actual ``DatabaseWrapper``
731 733
 object, use ``django.db.connections[DEFAULT_DB_ALIAS]`` instead.
732 734
 
@@ -747,7 +749,7 @@ Check their documentation for details.
747 749
 Django's :doc:`comments app </ref/contrib/comments/index>` has historically
748 750
 supported excluding the comments of a special user group, but we've never
749 751
 documented the feature properly and didn't enforce the exclusion in other parts
750  
-of the app, e.g., the template tags. To fix this problem, we removed the code
  752
+of the app such as the template tags. To fix this problem, we removed the code
751 753
 from the feed class.
752 754
 
753 755
 If you rely on the feature and want to restore the old behavior, simply use
@@ -785,10 +787,9 @@ For more details, see the documentation about
785 787
 `IGNORABLE_404_STARTS` and `IGNORABLE_404_ENDS` settings
786 788
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
787 789
 
788  
-Django can report 404 errors: see :doc:`/howto/error-reporting`.
789  
-Until Django 1.3, it was possible to exclude some URLs from the reporting
790  
-by adding prefixes to :setting:`IGNORABLE_404_STARTS` and suffixes to
791  
-:setting:`IGNORABLE_404_ENDS`.
  790
+Until Django 1.3, it was possible to exclude some URLs from Django's
  791
+:doc:`404 error reporting</howto/error-reporting>` by adding prefixes to
  792
+:setting:`IGNORABLE_404_STARTS` and suffixes to :setting:`IGNORABLE_404_ENDS`.
792 793
 
793 794
 In Django 1.4, these two settings are superseded by
794 795
 :setting:`IGNORABLE_404_URLS`, which is a list of compiled regular expressions.
@@ -882,8 +883,6 @@ whose primary use is to load fixtures consisting of simple objects. Even though
882 883
 fixtures are trusted data, for additional security, the YAML deserializer now
883 884
 uses ``yaml.safe_load``.
884 885
 
885  
-.. _deprecated-features-1.4:
886  
-
887 886
 Features deprecated in 1.4
888 887
 ==========================
889 888
 
@@ -900,7 +899,7 @@ Support for PostgreSQL versions older than 8.2
900 899
 Django 1.3 dropped support for PostgreSQL versions older than 8.0 and the
901 900
 relevant documents suggested to use a recent version because of performance
902 901
 reasons but more importantly because end of the upstream support periods for
903  
-releases 8.0 and 8.1 was near (November 2010.)
  902
+releases 8.0 and 8.1 was near (November 2010).
904 903
 
905 904
 Django 1.4 takes that policy further and sets 8.2 as the minimum PostgreSQL
906 905
 version it officially supports.
@@ -913,13 +912,13 @@ admin error email support was moved into the
913 912
 :class:`django.utils.log.AdminEmailHandler`, attached to the
914 913
 ``'django.request'`` logger. In order to maintain the established behavior of
915 914
 error emails, the ``'django.request'`` logger was called only when
916  
-:setting:`DEBUG` was `False`.
  915
+:setting:`DEBUG` was ``False``.
917 916
 
918  
-To increase the flexibility of request-error logging, the ``'django.request'``
919  
-logger is now called regardless of the value of :setting:`DEBUG`, and the
920  
-default settings file for new projects now includes a separate filter attached
921  
-to :class:`django.utils.log.AdminEmailHandler` to prevent admin error emails in
922  
-`DEBUG` mode::
  917
+To increase the flexibility of error logging for requests, the
  918
+``'django.request'`` logger is now called regardless of the value of
  919
+:setting:`DEBUG`, and the default settings file for new projects now includes a
  920
+separate filter attached to :class:`django.utils.log.AdminEmailHandler` to
  921
+prevent admin error emails in ``DEBUG`` mode::
923 922
 
924 923
    'filters': {
925 924
         'require_debug_false': {
@@ -958,13 +957,13 @@ Starting with Django 1.4 they are now available in :mod:`django.conf.urls`.
958 957
 ``django.contrib.databrowse``
959 958
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
960 959
 
961  
-Databrowse has not seen active development for some time, and this does not
962  
-show any sign of changing. There had been a suggestion for a GSOC project to
  960
+Databrowse has not seen active development for some time, and this does not show
  961
+any sign of changing. There had been a suggestion for a `GSOC project`_ to
963 962
 integrate the functionality of databrowse into the admin, but no progress was
964 963
 made. While Databrowse has been deprecated, an enhancement of
965  
-django.contrib.admin providing a similar feature set is still possible.
  964
+``django.contrib.admin`` providing a similar feature set is still possible.
966 965
 
967  
-.. _GSOC Proposal: https://code.djangoproject.com/wiki/SummerOfCode2011#Integratedatabrowseintotheadmin
  966
+.. _GSOC project: https://code.djangoproject.com/wiki/SummerOfCode2011#Integratedatabrowseintotheadmin
968 967
 
969 968
 The code that powers Databrowse is licensed under the same terms as Django
970 969
 itself, and so is available to be adopted by an individual or group as
@@ -978,10 +977,10 @@ This function temporarily modified ``sys.path`` in order to make the parent
978 977
 layout. This function is now deprecated, as its path workarounds are no longer
979 978
 needed with the new ``manage.py`` and default project layout.
980 979
 
981  
-This function was never documented or public API, but was widely recommended
982  
-for use in setting up a "Django environment" for a user script. These uses
983  
-should be replaced by setting the ``DJANGO_SETTINGS_MODULE`` environment
984  
-variable or using :func:`django.conf.settings.configure`.
  980
+This function was never documented or part of the public API, but was widely
  981
+recommended for use in setting up a "Django environment" for a user script.
  982
+These uses should be replaced by setting the ``DJANGO_SETTINGS_MODULE``
  983
+environment variable or using :func:`django.conf.settings.configure`.
985 984
 
986 985
 ``django.core.management.execute_manager``
987 986
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -989,10 +988,10 @@ variable or using :func:`django.conf.settings.configure`.
989 988
 This function was previously used by ``manage.py`` to execute a management
990 989
 command. It is identical to
991 990
 ``django.core.management.execute_from_command_line``, except that it first
992  
-calls ``setup_environ``, which is now deprecated. ``execute_manager`` is also