Fixed #13444 -- Improved the documentation around the backwards compatibility quirks of the cycle and include tags. Thanks to awmcclain for the report.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@13063 bcc190cf-cafb-0310-a4f2-bffc1f526a37

2 files changed, 35 insertions, 0 deletions

diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt
index 291abcb8cc..41bf683c22 100644
--- a/docs/ref/templates/builtins.txt
+++ b/docs/ref/templates/builtins.txt
@@ -619,6 +619,13 @@ including it. This example produces the output ``"Hello, John"``:
 
 See also: ``{% ssi %}``.
 
+.. note::
+    The :ttag:`include` tag should be considered as an implementation of
+    "render this subtemplate and include the HTML", not as "parse this
+    subtemplate and include its contents as if it were part of the parent".
+    This means that there is no shared state between included templates --
+    each include is a completely independent rendering process.
+
 .. templatetag:: load
 
 load
diff --git a/docs/releases/1.2.txt b/docs/releases/1.2.txt
index 0d61d1893f..31b95e4ace 100644
--- a/docs/releases/1.2.txt
+++ b/docs/releases/1.2.txt
@@ -230,6 +230,34 @@ party packages, or from your own code, you should ensure that the
 information, see
 :ref:`template tag thread safety considerations<template_tag_thread_safety>`.
 
+You may also need to update your templates if you were relying on the
+implementation of Django's template tags *not* being thread safe. The
+:ttag:`cycle` tag is the most likely to be affected in this way,
+especially when used in conjunction with the :ttag:`include` tag.
+Consider the following template fragment::
+
+    {% for object in object_list %}
+        {% include "subtemplate.html" %}
+    {% endfor %}
+
+with a ``subtemplate.html`` that reads::
+
+    {% cycle 'even' 'odd' %}
+
+Using the non thread-safe, pre-Django 1.2 renderer, this would output::
+
+    even odd even odd ...
+
+Using the thread-safe Django 1.2 renderer, you will instead get::
+
+    even even even even ...
+
+This is because the each rendering of the :ttag:`include` tag is an
+independent rendering. When the :ttag:`cycle` tag was not thread safe,
+the state of the :ttag:`cycle` tag would leak between multiple renderings
+of the same :ttag:`include`. Now that the :ttag:`cycle` tag is thread safe,
+this leakage no longer occurs.
+
 Test runner exit status code
 ----------------------------