From dd98ccd4821f71543a5489d421ea2dee28901f17 Mon Sep 17 00:00:00 2001
From: Tim Graham <timograham@gmail.com>
Date: Thu, 16 Jan 2014 21:13:08 -0500
Subject: [PATCH] Fixed #16785 -- Documented some of the design decisions of
 the cache framework.

Thanks jamesp for the draft patch.
---
 docs/misc/design-philosophies.txt | 26 ++++++++++++++++++++++++++
 docs/topics/cache.txt             |  4 ++++
 2 files changed, 30 insertions(+)

diff --git a/docs/misc/design-philosophies.txt b/docs/misc/design-philosophies.txt
index 8664d4e7ed..39807ed3d0 100644
--- a/docs/misc/design-philosophies.txt
+++ b/docs/misc/design-philosophies.txt
@@ -307,3 +307,29 @@ Differentiate between GET and POST
 
 GET and POST are distinct; developers should explicitly use one or the other.
 The framework should make it easy to distinguish between GET and POST data.
+
+.. _cache-design-philosophy:
+
+Cache Framework
+===============
+
+The core goals of Django's :doc:`cache framework </topics/cache>` are:
+
+Less code
+---------
+
+A cache should be as fast as possible.  Hence, all framework code surrounding
+the cache backend should be kept to the absolute minimum, especially for
+``get()`` operations.
+
+Consistency
+-----------
+
+The cache API should provide a consistent interface across the different
+cache backends.
+
+Extensibility
+-------------
+
+The cache API should be extensible at the application level based on the
+developer's needs (for example, see :ref:`cache_key_transformation`).
diff --git a/docs/topics/cache.txt b/docs/topics/cache.txt
index 37e94957db..c77a7288a5 100644
--- a/docs/topics/cache.txt
+++ b/docs/topics/cache.txt
@@ -39,6 +39,10 @@ Django also works well with "upstream" caches, such as `Squid
 caches that you don't directly control but to which you can provide hints (via
 HTTP headers) about which parts of your site should be cached, and how.
 
+.. seealso::
+    The :ref:`Cache Framework design philosophy <cache-design-philosophy>`
+    explains a few of the design decisions of the framework.
+
 .. _setting-up-the-cache:
 
 Setting up the cache