Django-1.2.1/docs/releases/1.0.txt

   1 .. _releases-1.0:
   2
   3 ========================
   4 Django 1.0 release notes
   5 ========================
   6
   7 Welcome to Django 1.0!
   8
   9 We've been looking forward to this moment for over three years, and it's finally
  10 here. Django 1.0 represents a the largest milestone in Django's development to
  11 date: a web framework that a group of perfectionists can truly be proud of.
  12
  13 Django 1.0 represents over three years of community development as an Open
  14 Source project. Django's received contributions from hundreds of developers,
  15 been translated into fifty languages, and today is used by developers on every
  16 continent and in every kind of job.
  17
  18 An interesting historical note: when Django was first released in July 2005, the
  19 initial released version of Django came from an internal repository at revision
  20 number 8825. Django 1.0 represents revision 8961 of our public repository. It
  21 seems fitting that our 1.0 release comes at the moment where community
  22 contributions overtake those made privately.
  23
  24 Stability and forwards-compatibility
  25 ====================================
  26
  27 :ref:`The release of Django 1.0 <releases-1.0>` comes with a promise of API
  28 stability and forwards-compatibility. In a nutshell, this means that code you
  29 develop against Django 1.0 will continue to work against 1.1 unchanged, and you
  30 should need to make only minor changes for any 1.X release.
  31
  32 See the :ref:`API stability guide <misc-api-stability>` for full details.
  33
  34 Backwards-incompatible changes
  35 ==============================
  36
  37 Django 1.0 has a number of backwards-incompatible changes from Django 0.96. If
  38 you have apps written against Django 0.96 that you need to port, see our
  39 detailed porting guide:
  40
  41 .. toctree::
  42    :maxdepth: 1
  43
  44    1.0-porting-guide
  45
  46 A complete list of backwards-incompatible changes can be found at
  47 http://code.djangoproject.com/wiki/BackwardsIncompatibleChanges.
  48
  49 What's new in Django 1.0
  50 ========================
  51
  52 A *lot*!
  53
  54 Since Django 0.96, we've made over 4,000 code commits, fixed more than 2,000
  55 bugs, and edited, added, or removed around 350,000 lines of code. We've also
  56 added 40,000 lines of new documentation, and greatly improved what was already
  57 there.
  58
  59 In fact, new documentation is one of our favorite features of Django 1.0, so we
  60 might as well start there. First, there's a new documentation site:
  61
  62     http://docs.djangoproject.com/
  63
  64 The documentation has been greatly improved, cleaned up, and generally made
  65 awesome. There's now dedicated search, indexes, and more.
  66
  67 We can't possibly document everything that's new in 1.0, but the documentation
  68 will be your definitive guide. Anywhere you see something like:
  69
  70 .. versionadded:: 1.0
  71    This feature is new in Django 1.0
  72
  73 You'll know that you're looking at something new or changed.
  74
  75 The other major highlights of Django 1.0 are:
  76
  77 Re-factored admin application
  78 -----------------------------
  79
  80 The Django administrative interface (``django.contrib.admin``) has been
  81 completely refactored; admin definitions are now completely decoupled from model
  82 definitions (no more ``class Admin`` declaration in models!), rewritten to use
  83 Django's new form-handling library (introduced in the 0.96 release as
  84 ``django.newforms``, and now available as simply ``django.forms``) and
  85 redesigned with extensibility and customization in mind. Full documentation for
  86 the admin application is available online in the official Django documentation:
  87
  88 See the :ref:`admin reference <ref-contrib-admin>` for details
  89
  90 Improved Unicode handling
  91 -------------------------
  92
  93 Django's internals have been refactored to use Unicode throughout; this
  94 drastically simplifies the task of dealing with non-Western-European content and
  95 data in Django. Additionally, utility functions have been provided to ease
  96 interoperability with third-party libraries and systems which may or may not
  97 handle Unicode gracefully. Details are available in Django's Unicode-handling
  98 documentation.
  99
 100 See :ref:`ref-unicode`.
 101
 102 An improved ORM
 103 ---------------
 104
 105 Django's object-relational mapper -- the component which provides the mapping
 106 between Django model classes and your database, and which mediates your database
 107 queries -- has been dramatically improved by a massive refactoring. For most
 108 users of Django this is backwards-compatible; the public-facing API for database
 109 querying underwent a few minor changes, but most of the updates took place in
 110 the ORM's internals. A guide to the changes, including backwards-incompatible
 111 modifications and mentions of new features opened up by this refactoring, is
 112 `available on the Django wiki`__.
 113
 114 __ http://code.djangoproject.com/wiki/QuerysetRefactorBranch
 115
 116 Automatic escaping of template variables
 117 ----------------------------------------
 118
 119 To provide improved security against cross-site scripting (XSS) vulnerabilities,
 120 Django's template system now automatically escapes the output of variables. This
 121 behavior is configurable, and allows both variables and larger template
 122 constructs to be marked as safe (requiring no escaping) or unsafe (requiring
 123 escaping). A full guide to this feature is in the documentation for the
 124 :ttag:`autoescape` tag.
 125
 126 ``django.contrib.gis`` (GeoDjango)
 127 ----------------------------------
 128
 129 A project over a year in the making, this adds world-class GIS (`Geographic
 130 Information Systems`_) support to Django, in the form of a ``contrib``
 131 application. Its documentation is currently being maintained externally, and
 132 will be merged into the main Django documentation shortly. Huge thanks go to
 133 Justin Bronn, Jeremy Dunck, Brett Hoerner and Travis Pinney for their efforts in
 134 creating and completing this feature.
 135
 136 See http://geodjango.org/ for details.
 137
 138 .. _Geographic Information Systems: http://en.wikipedia.org/wiki/Geographic_information_system
 139
 140 Pluggable file storage
 141 ----------------------
 142
 143 Django's built-in ``FileField`` and ``ImageField`` now can take advantage of
 144 pluggable file-storage backends, allowing extensive customization of where and
 145 how uploaded files get stored by Django. For details, see :ref:`the files
 146 documentation <topics-files>`; big thanks go to Marty Alchin for putting in the
 147 hard work to get this completed.
 148
 149 Jython compatibility
 150 --------------------
 151
 152 Thanks to a lot of work from Leo Soto during a Google Summer of Code project,
 153 Django's codebase has been refactored to remove incompatibilities with
 154 `Jython`_, an implementation of Python written in Java, which runs Python code
 155 on the Java Virtual Machine. Django is now compatible with the forthcoming
 156 Jython 2.5 release.
 157
 158 See :ref:`howto-jython`.
 159
 160 .. _Jython: http://www.jython.org/
 161
 162 Generic relations in forms and admin
 163 ------------------------------------
 164
 165 Classes are now included in ``django.contrib.contenttypes`` which can be used to
 166 support generic relations in both the admin interface and in end-user forms. See
 167 :ref:`the documentation for generic relations <generic-relations>` for details.
 168
 169 ``INSERT``/``UPDATE`` distinction
 170 ---------------------------------
 171
 172 Although Django's default behavior of having a model's ``save()`` method
 173 automatically determine whether to perform an ``INSERT`` or an ``UPDATE`` at the
 174 SQL level is suitable for the majority of cases, there are occasional situations
 175 where forcing one or the other is useful. As a result, models can now support an
 176 additional parameter to ``save()`` which can force a specific operation.
 177
 178 See :ref:`ref-models-force-insert` for details.
 179
 180 Split ``CacheMiddleware``
 181 -------------------------
 182
 183 Django's ``CacheMiddleware`` has been split into three classes:
 184 ``CacheMiddleware`` itself still exists and retains all of its previous
 185 functionality, but it is now built from two separate middleware classes which
 186 handle the two parts of caching (inserting into and reading from the cache)
 187 separately, offering additional flexibility for situations where combining these
 188 functions into a single middleware posed problems.
 189
 190 Full details, including updated notes on appropriate use, are in :ref:`the
 191 caching documentation <topics-cache>`.
 192
 193 Refactored ``django.contrib.comments``
 194 --------------------------------------
 195
 196 As part of a Google Summer of Code project, Thejaswi Puthraya carried out a
 197 major rewrite and refactoring of Django's bundled comment system, greatly
 198 increasing its flexibility and customizability. :ref:`Full documentation
 199 <ref-contrib-comments-index>` is available, as well as :ref:`an upgrade guide
 200 <ref-contrib-comments-upgrade>` if you were using the previous incarnation of
 201 the comments application.
 202
 203 Removal of deprecated features
 204 ------------------------------
 205
 206 A number of features and methods which had previously been marked as deprecated,
 207 and which were scheduled for removal prior to the 1.0 release, are no longer
 208 present in Django. These include imports of the form library from
 209 ``django.newforms`` (now located simply at ``django.forms``), the
 210 ``form_for_model`` and ``form_for_instance`` helper functions (which have been
 211 replaced by ``ModelForm``) and a number of deprecated features which were
 212 replaced by the dispatcher, file-uploading and file-storage refactorings
 213 introduced in the Django 1.0 alpha releases.
 214
 215 Known issues
 216 ============
 217
 218 We've done our best to make Django 1.0 as solid as possible, but unfortunately
 219 there are a couple of issues that we know about in the release.
 220
 221 Multi-table model inheritance with ``to_field``
 222 -----------------------------------------------
 223
 224 If you're using :ref:`multiple table model inheritance
 225 <multi-table-inheritance>`, be aware of this caveat: child models using a custom
 226 ``parent_link`` and ``to_field`` will cause database integrity errors. A set of
 227 models like the following are **not valid**::
 228
 229     class Parent(models.Model):
 230         name = models.CharField(max_length=10)
 231         other_value = models.IntegerField(unique=True)
 232
 233     class Child(Parent):
 234         father = models.OneToOneField(Parent, primary_key=True, to_field="other_value", parent_link=True)
 235         value = models.IntegerField()
 236
 237 This bug will be fixed in the next release of Django.
 238
 239 Caveats with support of certain databases
 240 -----------------------------------------
 241
 242 Django attempts to support as many features as possible on all database
 243 backends. However, not all database backends are alike, and in particular many of the supported database differ greatly from version to version. It's a good idea to checkout our :ref:`notes on supported database <ref-databases>`:
 244
 245     - :ref:`mysql-notes`
 246     - :ref:`sqlite-notes`
 247     - :ref:`oracle-notes`
 248