[soc2009/multidb] Merged up to trunk r11804.

git-svn-id: http://code.djangoproject.com/svn/django/branches/soc2009/multidb@11805 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/internals/contributing.txt

@@ -426,6 +426,47 @@ translated, here's what to do:
 
 .. _Django i18n mailing list: http://groups.google.com/group/django-i18n/
 
+Django conventions
+==================
+
+Various Django-specific code issues are detailed in this section.
+
+Use of ``django.conf.settings``
+-------------------------------
+
+Modules should not in general use settings stored in ``django.conf.settings`` at
+the top level (i.e. evaluated when the module is imported). The explanation for
+this is as follows:
+
+Manual configuration of settings (i.e. not relying on the
+``DJANGO_SETTINGS_MODULE`` environment variable) is allowed and possible as
+follows::
+
+    from django.conf import settings
+
+    settings.configure({}, SOME_SETTING='foo')
+
+However, if any setting is accessed before the ``settings.configure`` line, this
+will not work. (Internally, ``setttings`` is a ``LazyObject`` which configures
+itself automatically when the settings are accessed if it has not already been
+configured).
+
+So, if there is a module containg some code as follows::
+
+    from django.conf import settings
+    from django.core.urlresolvers import get_callable
+
+    default_foo_view = get_callable(settings.FOO_VIEW)
+
+...then importing this module will cause the settings object to be configured.
+That means that the ability for third parties to import the module at the top
+level is incompatible with the ability to configure the settings object
+manually, or makes it very difficult in some circumstances.
+
+Instead of the above code, a level of laziness or indirection must be used, such
+as :class:`django.utils.functional.LazyObject`, :func:`django.utils.functional.lazy` or
+``lambda``.
+
 Coding style
 ============
 

docs/internals/deprecation.txt

@@ -40,6 +40,14 @@ their deprecation, as per the :ref:`Django deprecation policy
           multiple databases. In 1.4, the support functions that allow methods
           with the old prototype to continue working will be removed.
 
+        * The ``Message`` model (in ``django.contrib.auth``), its related
+          manager in the ``User`` model (``user.message_set``), and the
+          associated methods (``user.message_set.create()`` and
+          ``user.get_and_delete_messages()``), which have
+          been deprecated since the 1.2 release, will be removed.  The 
+          :ref:`messages framework <ref-contrib-messages>` should be used 
+          instead.
+
     * 2.0
         * ``django.views.defaults.shortcut()``. This function has been moved
           to ``django.contrib.contenttypes.views.shortcut()`` as part of the