| 1 |
========================== |
| 2 |
Django 1.2.5 release notes |
| 3 |
========================== |
| 4 |
|
| 5 |
Welcome to Django 1.2.5! |
| 6 |
|
| 7 |
This is the fifth "bugfix" release in the Django 1.2 series, |
| 8 |
improving the stability and performance of the Django 1.2 codebase. |
| 9 |
|
| 10 |
With four exceptions, Django 1.2.5 maintains backwards compatibility |
| 11 |
with Django 1.2.4. It also contains a number of fixes and other |
| 12 |
improvements. Django 1.2.5 is a recommended upgrade for any |
| 13 |
development or deployment currently using or targeting Django 1.2. |
| 14 |
|
| 15 |
For full details on the new features, backwards incompatibilities, and |
| 16 |
deprecated features in the 1.2 branch, see the :doc:`/releases/1.2`. |
| 17 |
|
| 18 |
Backwards incompatible changes |
| 19 |
============================== |
| 20 |
|
| 21 |
CSRF exception for AJAX requests |
| 22 |
-------------------------------- |
| 23 |
|
| 24 |
Django includes a CSRF-protection mechanism, which makes use of a |
| 25 |
token inserted into outgoing forms. Middleware then checks for the |
| 26 |
token's presence on form submission, and validates it. |
| 27 |
|
| 28 |
Prior to Django 1.2.5, our CSRF protection made an exception for AJAX |
| 29 |
requests, on the following basis: |
| 30 |
|
| 31 |
* Many AJAX toolkits add an X-Requested-With header when using |
| 32 |
XMLHttpRequest. |
| 33 |
|
| 34 |
* Browsers have strict same-origin policies regarding |
| 35 |
XMLHttpRequest. |
| 36 |
|
| 37 |
* In the context of a browser, the only way that a custom header |
| 38 |
of this nature can be added is with XMLHttpRequest. |
| 39 |
|
| 40 |
Therefore, for ease of use, we did not apply CSRF checks to requests |
| 41 |
that appeared to be AJAX on the basis of the X-Requested-With header. |
| 42 |
The Ruby on Rails web framework had a similar exemption. |
| 43 |
|
| 44 |
Recently, engineers at Google made members of the Ruby on Rails |
| 45 |
development team aware of a combination of browser plugins and |
| 46 |
redirects which can allow an attacker to provide custom HTTP headers |
| 47 |
on a request to any website. This can allow a forged request to appear |
| 48 |
to be an AJAX request, thereby defeating CSRF protection which trusts |
| 49 |
the same-origin nature of AJAX requests. |
| 50 |
|
| 51 |
Michael Koziarski of the Rails team brought this to our attention, and |
| 52 |
we were able to produce a proof-of-concept demonstrating the same |
| 53 |
vulnerability in Django's CSRF handling. |
| 54 |
|
| 55 |
To remedy this, Django will now apply full CSRF validation to all |
| 56 |
requests, regardless of apparent AJAX origin. This is technically |
| 57 |
backwards-incompatible, but the security risks have been judged to |
| 58 |
outweigh the compatibility concerns in this case. |
| 59 |
|
| 60 |
Additionally, Django will now accept the CSRF token in the custom HTTP |
| 61 |
header X-CSRFTOKEN, as well as in the form submission itself, for ease |
| 62 |
of use with popular JavaScript toolkits which allow insertion of |
| 63 |
custom headers into all AJAX requests. |
| 64 |
|
| 65 |
Please see the :ref:`CSRF docs for example jQuery code <csrf-ajax>` |
| 66 |
that demonstrates this technique, ensuring that you are looking at the |
| 67 |
documentation for your version of Django, as the exact code necessary |
| 68 |
is different for some older versions of Django. |
| 69 |
|
| 70 |
FileField no longer deletes files |
| 71 |
--------------------------------- |
| 72 |
|
| 73 |
In earlier Django versions, when a model instance containing a |
| 74 |
:class:`~django.db.models.FileField` was deleted, |
| 75 |
:class:`~django.db.models.FileField` took it upon itself to also delete the |
| 76 |
file from the backend storage. This opened the door to several potentially |
| 77 |
serious data-loss scenarios, including rolled-back transactions and fields on |
| 78 |
different models referencing the same file. In Django 1.2.5, |
| 79 |
:class:`~django.db.models.FileField` will never delete files from the backend |
| 80 |
storage. If you need cleanup of orphaned files, you'll need to handle it |
| 81 |
yourself (for instance, with a custom management command that can be run |
| 82 |
manually or scheduled to run periodically via e.g. cron). |
| 83 |
|
| 84 |
Use of custom SQL to load initial data in tests |
| 85 |
----------------------------------------------- |
| 86 |
|
| 87 |
Django provides a custom SQL hooks as a way to inject hand-crafted SQL |
| 88 |
into the database synchronization process. One of the possible uses |
| 89 |
for this custom SQL is to insert data into your database. If your |
| 90 |
custom SQL contains ``INSERT`` statements, those insertions will be |
| 91 |
performed every time your database is synchronized. This includes the |
| 92 |
synchronization of any test databases that are created when you run a |
| 93 |
test suite. |
| 94 |
|
| 95 |
However, in the process of testing the Django 1.3, it was discovered |
| 96 |
that this feature has never completely worked as advertised. When |
| 97 |
using database backends that don't support transactions, or when using |
| 98 |
a TransactionTestCase, data that has been inserted using custom SQL |
| 99 |
will not be visible during the testing process. |
| 100 |
|
| 101 |
Unfortunately, there was no way to rectify this problem without |
| 102 |
introducing a backwards incompatibility. Rather than leave |
| 103 |
SQL-inserted initial data in an uncertain state, Django now enforces |
| 104 |
the policy that data inserted by custom SQL will *not* be visible |
| 105 |
during testing. |
| 106 |
|
| 107 |
This change only affects the testing process. You can still use custom |
| 108 |
SQL to load data into your production database as part of the ``syncdb`` |
| 109 |
process. If you require data to exist during test conditions, you |
| 110 |
should either insert it using :ref:`test fixtures |
| 111 |
<topics-testing-fixtures>`, or using the ``setUp()`` method of your |
| 112 |
test case. |
| 113 |
|
| 114 |
ModelAdmin.lookup_allowed signature changed |
| 115 |
------------------------------------------- |
| 116 |
|
| 117 |
Django 1.2.4 introduced a method ``lookup_allowed`` on ``ModelAdmin``, to cope |
| 118 |
with a security issue (changeset :commit:`[15033] |
| 119 |
<85207a245bf09fdebe486b4c7bbcb65300f2a693>`). Although this method was never |
| 120 |
documented, it seems some people have overridden ``lookup_allowed``, especially |
| 121 |
to cope with regressions introduced by that changeset. While the method is |
| 122 |
still undocumented and not marked as stable, it may be helpful to know that the |
| 123 |
signature of this function has changed. |