Fixed #23384 -- Allowed overriding part of a dictionary-type setting

This change is needed for upcoming changes where settings might be
grouped in a parent dictionary.
Thanks Tim Graham for the review.

2 files changed, 29 insertions, 0 deletions

diff --git a/docs/releases/1.8.txt b/docs/releases/1.8.txt
index 42728b2a7c..f060691d83 100644
--- a/docs/releases/1.8.txt
+++ b/docs/releases/1.8.txt
@@ -530,6 +530,9 @@ Miscellaneous
   widget to allow more customization. The undocumented ``url_markup_template``
   attribute was removed in favor of ``template_with_initial``.
 
+* When a dictionary setting is overridden in user settings, both dictionaries
+  are merged by default. See :ref:`dictionary-settings`.
+
 .. _deprecated-features-1.8:
 
 Features deprecated in 1.8
diff --git a/docs/topics/settings.txt b/docs/topics/settings.txt
index 2024d88a0f..cc9cc21652 100644
--- a/docs/topics/settings.txt
+++ b/docs/topics/settings.txt
@@ -110,6 +110,32 @@ between the current settings file and Django's default settings.
 
 For more, see the :djadmin:`diffsettings` documentation.
 
+.. _dictionary-settings:
+
+Overriding dictionary settings
+------------------------------
+
+.. versionchanged:: 1.8
+
+When defining a dictionary-type setting which has a non-empty value (see
+:setting:`CACHES` for example), you do not have to redefine all its keys. You
+can just define the keys differing from the default, and Django will simply
+merge your setting value with the default value. For example, if you define
+:setting:`CACHES` so::
+
+    CACHES = {
+        'special': {
+            'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache',
+            'LOCATION': '127.0.0.1:11211',
+        }
+    }
+
+then ``CACHES['default']`` which is set by default in Django's global settings
+will still be defined, as well as the new ``'special'`` cache backend.
+
+If you want your setting to completely override the default value, you can add
+a ``_clear_defaults`` key with a ``True`` value to the dictionary.
+
 Using settings in Python code
 =============================