docs/release_notes_0.96.txt

   1 =================================
   2 Django version 0.96 release notes
   3 =================================
   4
   5 Welcome to Django 0.96!
   6
   7 The primary goal for 0.96 is a cleanup and stabilization of the features
   8 introduced in 0.95. There have been a few small `backwards-incompatible
   9 changes`_ since 0.95, but the upgrade process should be fairly simple
  10 and should not require major changes to existing applications.
  11
  12 However, we're also releasing 0.96 now because we have a set of
  13 backwards-incompatible changes scheduled for the near future. Once
  14 completed, they will involve some code changes for application
  15 developers, so we recommend that you stick with Django 0.96 until the
  16 next official release; then you'll be able to upgrade in one step
  17 instead of needing to make incremental changes to keep up with the
  18 development version of Django.
  19
  20 Backwards-incompatible changes
  21 ==============================
  22
  23 The following changes may require you to update your code when you switch from
  24 0.95 to 0.96:
  25
  26 `MySQLdb` version requirement
  27 -----------------------------
  28
  29 Due to a bug in older versions of the `MySQLdb` Python module (which
  30 Django uses to connect to MySQL databases), Django's MySQL backend now
  31 requires version 1.2.1p2 or higher of `MySQLdb`, and will raise
  32 exceptions if you attempt to use an older version.
  33
  34 If you're currently unable to upgrade your copy of `MySQLdb` to meet
  35 this requirement, a separate, backwards-compatible backend, called
  36 "mysql_old", has been added to Django. To use this backend, change
  37 the ``DATABASE_ENGINE`` setting in your Django settings file from
  38 this::
  39
  40     DATABASE_ENGINE = "mysql"
  41
  42 to this::
  43
  44     DATABASE_ENGINE = "mysql_old"
  45
  46 However, we strongly encourage MySQL users to upgrade to a more recent
  47 version of `MySQLdb` as soon as possible, The "mysql_old" backend is
  48 provided only to ease this transition, and is considered deprecated;
  49 aside from any necessary security fixes, it will not be actively
  50 maintained, and it will be removed in a future release of Django.
  51
  52 Also, note that some features, like the new ``DATABASE_OPTIONS``
  53 setting (see the `databases documentation`_ for details), are only
  54 available on the "mysql" backend, and will not be made available for
  55 "mysql_old".
  56
  57 .. _databases documentation: ../databases/
  58
  59 Database constraint names changed
  60 ---------------------------------
  61
  62 The format of the constraint names Django generates for foreign key
  63 references have changed slightly. These names are generally only used
  64 when it is not possible to put the reference directly on the affected
  65 column, so they is not always visible.
  66
  67 The effect of this change is that running ``manage.py reset`` and
  68 similar commands against an existing database may generate SQL with
  69 the new form of constraint name, while the database itself contains
  70 constraints named in the old form; this will cause the database server
  71 to raise an error message about modifying non-existent constraints.
  72
  73 If you need to work around this, there are two methods available:
  74
  75     1. Redirect the output of ``manage.py`` to a file, and edit the
  76        generated SQL to use the correct constraint names before
  77        executing it.
  78
  79     2. Examine the output of ``manage.py sqlall`` to see the new-style
  80        constraint names, and use that as a guide to rename existing
  81        constraints in your database.
  82
  83 Names changes in ``manage.py``
  84 ------------------------------
  85
  86 A few of the options to ``manage.py`` have changed with the addition of fixture
  87 support:
  88
  89     * There are new ``dumpdata`` and ``loaddata`` commands which, as
  90       you might expect, will dump and load data to/from the
  91       database. These commands can operate against any of Django's
  92       supported serialization formats.
  93
  94     * The ``sqlinitialdata`` command has been renamed to ``sqlcustom`` to
  95       emphasize that ``loaddata`` should be used for data (and ``sqlcustom`` for
  96       other custom SQL -- views, stored procedures, etc.).
  97
  98     * The vestigial ``install`` command has been removed. Use ``syncdb``.
  99
 100 Backslash escaping changed
 101 --------------------------
 102
 103 The Django database API now escapes backslashes given as query parameters. If
 104 you have any database API code that matches backslashes, and it was working before
 105 (despite the lack of escaping), you'll have to change your code to "unescape" the
 106 slashes one level.
 107
 108 For example, this used to work::
 109
 110     # Find text containing a single backslash
 111     MyModel.objects.filter(text__contains='\\\\')
 112
 113 The above is now incorrect, and should be rewritten as::
 114
 115     # Find text containing a single backslash
 116     MyModel.objects.filter(text__contains='\\')
 117
 118 Removed ENABLE_PSYCO setting
 119 ----------------------------
 120
 121 The ``ENABLE_PSYCO`` setting no longer exists. If your settings file includes
 122 ``ENABLE_PSYCO`` it will have no effect; to use Psyco_, we recommend
 123 writing a middleware class to activate it.
 124
 125 .. _psyco: http://psyco.sourceforge.net/
 126
 127 What's new in 0.96?
 128 ===================
 129
 130 This revision represents over a thousand source commits and over four hundred
 131 bug fixes, so we can't possibly catalog all the changes. Here, we describe the
 132 most notable changes in this release.
 133
 134 New forms library
 135 -----------------
 136
 137 ``django.newforms`` is Django's new form-handling library. It's a
 138 replacement for ``django.forms``, the old form/manipulator/validation
 139 framework.  Both APIs are available in 0.96, but over the next two
 140 releases we plan to switch completely to the new forms system, and
 141 deprecate and remove the old system.
 142
 143 There are three elements to this transition:
 144
 145     * We've copied the current ``django.forms`` to
 146       ``django.oldforms``. This allows you to upgrade your code *now*
 147       rather than waiting for the backwards-incompatible change and
 148       rushing to fix your code after the fact.  Just change your
 149       import statements like this::
 150
 151           from django import forms             # 0.95-style
 152           from django import oldforms as forms # 0.96-style
 153
 154     * The next official release of Django will move the current
 155       ``django.newforms`` to ``django.forms``. This will be a
 156       backwards-incompatible change, and anyone still using the old
 157       version of ``django.forms`` at that time will need to change
 158       their import statements as described above.
 159
 160     * The next release after that will completely remove
 161       ``django.oldforms``.
 162
 163 Although the ``newforms`` library will continue to evolve, it's ready for use
 164 for most common cases. We recommend that anyone new to form handling skip the
 165 old forms system and start with the new.
 166
 167 For more information about ``django.newforms``, read the `newforms
 168 documentation`_.
 169
 170 .. _newforms documentation: ../newforms/
 171
 172 URLconf improvements
 173 --------------------
 174
 175 You can now use any callable as the callback in URLconfs (previously, only
 176 strings that referred to callables were allowed). This allows a much more
 177 natural use of URLconfs. For example, this URLconf::
 178
 179     from django.conf.urls.defaults import *
 180
 181     urlpatterns = patterns('',
 182         ('^myview/$', 'mysite.myapp.views.myview')
 183     )
 184
 185 can now be rewritten as::
 186
 187     from django.conf.urls.defaults import *
 188     from mysite.myapp.views import myview
 189
 190     urlpatterns = patterns('',
 191         ('^myview/$', myview)
 192     )
 193
 194 One useful application of this can be seen when using decorators; this
 195 change allows you to apply decorators to views *in your
 196 URLconf*. Thus, you can make a generic view require login very
 197 easily::
 198
 199     from django.conf.urls.defaults import *
 200     from django.contrib.auth.decorators import login_required
 201     from django.views.generic.list_detail import object_list
 202     from mysite.myapp.models import MyModel
 203
 204     info = {
 205         "queryset" : MyModel.objects.all(),
 206     }
 207
 208     urlpatterns = patterns('',
 209         ('^myview/$', login_required(object_list), info)
 210     )
 211
 212 Note that both syntaxes (strings and callables) are valid, and will continue to
 213 be valid for the foreseeable future.
 214
 215 The test framework
 216 ------------------
 217
 218 Django now includes a test framework so you can start transmuting fear into
 219 boredom (with apologies to Kent Beck). You can write tests based on doctest_
 220 or unittest_ and test your views with a simple test client.
 221
 222 There is also new support for "fixtures" -- initial data, stored in any of the
 223 supported `serialization formats`_, that will be loaded into your database at the
 224 start of your tests. This makes testing with real data much easier.
 225
 226 See `the testing documentation`_ for the full details.
 227
 228 .. _doctest: http://docs.python.org/lib/module-doctest.html
 229 .. _unittest: http://docs.python.org/lib/module-unittest.html
 230 .. _the testing documentation: ../testing/
 231 .. _serialization formats: ../serialization/
 232
 233 Improvements to the admin interface
 234 -----------------------------------
 235
 236 A small change, but a very nice one: dedicated views for adding and
 237 updating users have been added to the admin interface, so you no
 238 longer need to worry about working with hashed passwords in the admin.
 239
 240 Thanks
 241 ======
 242
 243 Since 0.95, a number of people have stepped forward and taken a major
 244 new role in Django's development. We'd like to thank these people for
 245 all their hard work:
 246
 247     * Russell Keith-Magee and Malcolm Tredinnick for their major code
 248       contributions. This release wouldn't have been possible without them.
 249
 250     * Our new release manager, James Bennett, for his work in getting out
 251       0.95.1, 0.96, and (hopefully) future release.
 252
 253     * Our ticket managers Chris Beaven (aka SmileyChris), Simon Greenhill,
 254       Michael Radziej, and Gary Wilson. They agreed to take on the monumental
 255       task of wrangling our tickets into nicely cataloged submission. Figuring
 256       out what to work on is now about a million times easier; thanks again,
 257       guys.
 258
 259     * Everyone who submitted a bug report, patch or ticket comment. We can't
 260       possibly thank everyone by name -- over 200 developers submitted patches
 261       that went into 0.96 -- but everyone who's contributed to Django is listed
 262       in AUTHORS_.
 263
 264 .. _AUTHORS: http://code.djangoproject.com/browser/django/trunk/AUTHORS