Some work on the 0.96 release notes

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

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
+changes`_ since 0.95, but the upgrade process should be fairly simple
-updates.
+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
+backwards-incompatible changes scheduled for the near future. Once
-will require code changes for developers tracking the Django development
+completed, they will involve some code changes for application
-version, so if you're looking for a rock-solid, stable, version of Django we
+developers, so we recommend that you stick with Django 0.96 until the
-recommend you stick with Django until the next official release and upgrade all
+next official release; then you'll be able to upgrade in one step
-at once.
+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
+``django.newforms`` is Django's new form-handling library. It's a
-replacement for ``django.forms``, the old form/manipulator/validation framework.
+replacement for ``django.forms``, the old form/manipulator/validation
-Both APIs are available in 0.96, but over the next two releases we plan to
+framework.  Both APIs are available in 0.96, but over the next two
-completely replace the old forms framework with this new one.
+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
+    * We've copied the current ``django.forms`` to
-      allows you to upgrade your code *now* rather than waiting for the
+      ``django.oldforms``. This allows you to upgrade your code *now*
-      backwards-incompatible change and rushing to fix your code after the fact.
+      rather than waiting for the backwards-incompatible change and
-      Just change your import statements like this::
+      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
+    * The next official release of Django will move the current
-      ``django.forms``. This will be a backwards-incompatible change, and
+      ``django.newforms`` to ``django.forms``. This will be a
-      anybody who is still using the old version of ``django.forms`` at that
+      backwards-incompatible change, and anyone still using the old
-      time will need to change their import statements, as described in the
+      version of ``django.forms`` at that time will need to change
-      previous bullet.
+      their import statements as described above.
 
-    * We will remove ``django.oldforms`` in the release *after* the next Django
+    * The next release after that will completely remove
-      release -- the release that comes after the release in which we're
+      ``django.oldforms``.
-      creating the new ``django.forms``.
 
 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
+One useful application of this can be seen when using decorators; this
-allows you to apply decorators to views *in your URLconf*. Thus, you can make a
+change allows you to apply decorators to views *in your
-generic view require login very easily::
+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
+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
+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: 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.
-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!
 
 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
+The format of the constraint names Django generates for foreign key
-changed slightly. These names are only used sometimes, when it is not possible
+references have changed slightly. These names are generally only used
-to put the reference directly on the affected column, so this is not always
+when it is not possible to put the reference directly on the affected
-visible.
+column, so they is not always visible.
 
-The effect of this change is that ``manage.py reset`` and similar commands may
+The effect of this change is that running ``manage.py reset`` and
-generate SQL with new constraint names and thus generate an error when run
+similar commands against an existing database may generate SQL with
-against the database (the database server will complain about the constraint not
+the new form of constraint name, while the database itself contains
-existing). To fix this, you will need to tweak the output of ``manage.py``
+constraints named in the old form; this will cause the database server
-to match the correct constraint names and pass the results to the
+to raise an error message about modifying non-existent constraints.
-database server manually. 
 
-You can also fix this by examining the output of ``manage.py sqlall`` and
+If you need to work around this, there are two methods available:
-renaming database constraints to match the new naming scheme.
+
+    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
+    * There are new ``dumpdata`` and ``loaddata`` commands which, as
-      expect, will dump and load data to/from the database. These targets
+      you might expect, will dump and load data to/from the
-      operate against one of the serialization formats.
+      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
+you have any database API code that matches backslashes, and it was working before
-(despite the broken escaping), you'll have to change your code to "unescape" the
+(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.
+``ENABLE_PSYCO`` it will have no effect; to use Psyco, we recommend
-
+writing a middleware class to activate it.
-If you want to use Psyco_ with Django, you'll need to write some custom
-middleware that activates Psyco.
 
 .. _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
+Since 0.95, a number of people have stepped forward and taken a major
-people for all their hard work:
+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.