diff --git a/docs/release_notes_0.96.txt b/docs/release_notes_0.96.txt index 94963cdafe..68cce395dc 100644 --- a/docs/release_notes_0.96.txt +++ b/docs/release_notes_0.96.txt @@ -6,15 +6,16 @@ Welcome to Django 0.96! The primary goal for 0.96 is a cleanup and stabilization of the features introduced in 0.95. There have been a few small `backwards-incompatible -changes`_ since 0.95, but nearly all changes shouldn't require any major -updates. +changes`_ since 0.95, but the upgrade process should be fairly simple +and should not require major changes to existing applications. However, we're also releasing 0.96 now because we have a set of -backwards-incompatible changes scheduled for the near future. These changes are -will require code changes for developers tracking the Django development -version, so if you're looking for a rock-solid, stable, version of Django we -recommend you stick with Django until the next official release and upgrade all -at once. +backwards-incompatible changes scheduled for the near future. Once +completed, they will involve some code changes for application +developers, so we recommend that you stick with Django 0.96 until the +next official release; then you'll be able to upgrade in one step +instead of needing to make incremental changes to keep up with the +development version of Django. What's new in 0.96? =================== @@ -26,34 +27,35 @@ most notable changes in this release. New forms library ----------------- -``django.newforms`` is Django's fantastic new form-handling library. It's a -replacement for ``django.forms``, the old form/manipulator/validation framework. -Both APIs are available in 0.96, but over the next two releases we plan to -completely replace the old forms framework with this new one. +``django.newforms`` is Django's new form-handling library. It's a +replacement for ``django.forms``, the old form/manipulator/validation +framework. Both APIs are available in 0.96, but over the next two +releases we plan to switch completely to the new forms system, and +deprecate and remove the old system. -Our transition plan is: +There are three elements to this transition: - * We've copied the current ``django.forms`` to ``django.oldforms``. This - allows you to upgrade your code *now* rather than waiting for the - backwards-incompatible change and rushing to fix your code after the fact. - Just change your import statements like this:: + * We've copied the current ``django.forms`` to + ``django.oldforms``. This allows you to upgrade your code *now* + rather than waiting for the backwards-incompatible change and + rushing to fix your code after the fact. Just change your + import statements like this:: from django import forms # 0.95-style from django import oldforms as forms # 0.96-style - * Before the next release, we will move the current ``django.newforms`` to - ``django.forms``. This will be a backwards-incompatible change, and - anybody who is still using the old version of ``django.forms`` at that - time will need to change their import statements, as described in the - previous bullet. + * The next official release of Django will move the current + ``django.newforms`` to ``django.forms``. This will be a + backwards-incompatible change, and anyone still using the old + version of ``django.forms`` at that time will need to change + their import statements as described above. - * We will remove ``django.oldforms`` in the release *after* the next Django - release -- the release that comes after the release in which we're - creating the new ``django.forms``. + * The next release after that will completely remove + ``django.oldforms``. Although the ``newforms`` library will continue to evolve, it's ready for use for most common cases. We recommend that anyone new to form handling skip the -old forms and start with the new. +old forms system and start with the new. For more information about ``django.newforms``, read the `newforms documentation`_. @@ -82,9 +84,10 @@ can now be rewritten as:: ('^myview/$', myview) ) -A very useful application of this can be seen when using decorators: this change -allows you to apply decorators to views *in your URLconf*. Thus, you can make a -generic view require login very easily:: +One useful application of this can be seen when using decorators; this +change allows you to apply decorators to views *in your +URLconf*. Thus, you can make a generic view require login very +easily:: from django.conf.urls.defaults import * from django.contrib.auth.decorators import login_required @@ -109,8 +112,8 @@ Django now includes a test framework so you can start transmuting fear into boredom (with apologies to Kent Beck). You can write tests based on doctest_ or unittest_ and test your views with a simple test client. -There is also new support for "fixtures" -- initial data stored in any of the -supported `serialization formats`_ that will be loaded into your database at the +There is also new support for "fixtures" -- initial data, stored in any of the +supported `serialization formats`_, that will be loaded into your database at the start of your tests. This makes testing with real data much easier. See `the testing documentation`_ for the full details. @@ -120,14 +123,12 @@ See `the testing documentation`_ for the full details. .. _the testing documentation: ../testing/ .. _serialization formats: ../serialization/ +Improvements to the admin interface +----------------------------------- -Improvements to the user admin interface ----------------------------------------- - -A small change, but a very nice one: you no longer need to edit MD5 hashes when -creating and/or updating users from the admin interface. - -Django is now hash-free for over a thousand revisions! +A small change, but a very nice one: dedicated views for adding and +updating users have been added to the admin interface, so you no +longer need to worry about working with hashed passwords in the admin. Backwards-incompatible changes ============================== @@ -135,23 +136,56 @@ Backwards-incompatible changes The following changes may require you to update your code when you switch from 0.95 to 0.96: +`MySQLdb` version requirement +----------------------------- + +Due to a bug in older versions of the `MySQLdb` Python module (which +Django uses to connect to MySQL databases), Django's MySQL backend now +requires version 1.2.1p2 or higher of `MySQLdb`, and will raise +exceptions if you attempt to use an older version. + +If you're currently unable to upgrade your copy of `MySQLdb` to meet +this requirement, a separate, backwards-compatible backend, called +"mysql_old", has been added to Django. To use this backend, change +the ``DATABASE_ENGINE`` setting in your Django settings file from +this:: + + DATABASE_ENGINE = "mysql" + +to this:: + + DATABASE_ENGINE = "mysql_old" + +However, we strongly encourage MySQL users to upgrade to a more recent +version of `MySQLdb` as soon as possible, The "mysql_old" backend is +provided only to ease this transition, and is considered deprecated; +aside from any necessary security fixes, it will not be actively +maintained, and it will be removed in a future release of Django. + + Database constraint names changed --------------------------------- -The format of the constraint names Django generates for foreign key references -changed slightly. These names are only used sometimes, when it is not possible -to put the reference directly on the affected column, so this is not always -visible. +The format of the constraint names Django generates for foreign key +references have changed slightly. These names are generally only used +when it is not possible to put the reference directly on the affected +column, so they is not always visible. -The effect of this change is that ``manage.py reset`` and similar commands may -generate SQL with new constraint names and thus generate an error when run -against the database (the database server will complain about the constraint not -existing). To fix this, you will need to tweak the output of ``manage.py`` -to match the correct constraint names and pass the results to the -database server manually. +The effect of this change is that running ``manage.py reset`` and +similar commands against an existing database may generate SQL with +the new form of constraint name, while the database itself contains +constraints named in the old form; this will cause the database server +to raise an error message about modifying non-existent constraints. -You can also fix this by examining the output of ``manage.py sqlall`` and -renaming database constraints to match the new naming scheme. +If you need to work around this, there are two methods available: + + 1. Redirect the output of ``manage.py`` to a file, and edit the + generated SQL to use the correct constraint names before + executing it. + + 2. Examine the output of ``manage.py sqlall`` to see the new-style + constraint names, and use that as a guide to rename existing + constraints in your database. Names changes in ``manage.py`` ------------------------------ @@ -159,22 +193,23 @@ Names changes in ``manage.py`` A few of the options to ``manage.py`` have changed with the addition of fixture support: - * There are new ``dumpdata`` and ``loaddata`` commands, which, as you might - expect, will dump and load data to/from the database. These targets - operate against one of the serialization formats. + * There are new ``dumpdata`` and ``loaddata`` commands which, as + you might expect, will dump and load data to/from the + database. These commands can operate against any of Django's + supported serialization formats. - * The ``sqlinitialdata`` target has been renamed to ``sqlcustom`` to + * The ``sqlinitialdata`` command has been renamed to ``sqlcustom`` to emphasize that ``loaddata`` should be used for data (and ``sqlcustom`` for other custom SQL -- views, stored procedures, etc.). - * The vestigal ``install`` target is gone. Use ``syncdb``. + * The vestigial ``install`` command has been removed. Use ``syncdb``. Backslash escaping changed -------------------------- The Django database API now escapes backslashes given as query parameters. If -you have any database API code that match backslashes, and it was working before -(despite the broken escaping), you'll have to change your code to "unescape" the +you have any database API code that matches backslashes, and it was working before +(despite the lack of escaping), you'll have to change your code to "unescape" the slashes one level. For example, this used to work:: @@ -191,18 +226,17 @@ Removed ENABLE_PSYCO setting ---------------------------- The ``ENABLE_PSYCO`` setting no longer exists. If your settings file includes -``ENABLE_PSYCO``, nothing will break per se, but it just won't do anything. - -If you want to use Psyco_ with Django, you'll need to write some custom -middleware that activates Psyco. +``ENABLE_PSYCO`` it will have no effect; to use Psyco, we recommend +writing a middleware class to activate it. .. _psyco: http://psyco.sourceforge.net/ Thanks ====== -Since 0.95, a number of people have stepped forward and taken a major new role in Django's development. We'd like to thank these -people for all their hard work: +Since 0.95, a number of people have stepped forward and taken a major +new role in Django's development. We'd like to thank these people for +all their hard work: * Russell Keith-Magee and Malcolm Tredinnick for their major code contributions. This release wouldn't have been possible without them.