Added release notes about the removal of Django 1.2 compatibility fal…

…lbacks for signed data

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

docs/releases/1.4.txt

@@ -21,3 +21,60 @@ What's new in Django 1.4
 
 Backwards incompatible changes in 1.4
 =====================================
+
+Compatibility with old signed data
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Django 1.3 changed the cryptographic signing mechanisms used in a number of
+places in Django. While Django 1.3 kept fallbacks that would accept hashes
+produced by the previous methods, these fallbacks are removed in Django 1.4.
+
+So, if you upgrade to Django 1.4 directly from 1.2 or earlier, you may
+lose/invalidate certain pieces of data that have been cryptographically signed
+using an old method. To avoid this, use Django 1.3 first, for a period of time,
+to allow the signed data to expire naturally. The affected parts are detailed
+below, with 1) the consequences of ignoring this advice and 2) the amount of
+time you need to run Django 1.3 for the data to expire or become irrelevant.
+
+* contrib.sessions data integrity check
+
+  * consequences: the user will be logged out, and session data will be lost.
+
+  * time period: defined by SESSION_COOKIE_AGE.
+
+* contrib.auth password reset hash
+
+  * consequences: password reset links from before the upgrade will not work.
+
+  * time period: defined by PASSWORD_RESET_TIMEOUT_DAYS.
+
+Form related hashes — these are much shorter lifetime, and are relevant only for
+the short window where a user might fill in a form generated by the pre-upgrade
+Django instance, and try to submit it to the upgraded Django instance:
+
+* contrib.comments form security hash
+
+  * consequences: the user will see a validation error "Security hash failed".
+
+  * time period: the amount of time you expect users to take filling out comment
+    forms.
+
+* FormWizard security hash
+
+  * consequences: the user will see an error about the form having expired,
+    and will be sent back to the first page of the wizard, losing the data
+    they have inputted so far.
+
+  * time period: the amount of time you expect users to take filling out the
+    affected forms.
+
+* CSRF check
+
+  * Note: This is actually a Django 1.1 fallback, not Django 1.2,
+    and applies only if you are upgrading from 1.1.
+
+  * consequences: the user will see a 403 error with any CSRF protected POST
+    form.
+
+  * time period: the amount of time you expect user to take filling out
+    such forms.