[1.2.X] Fixed #12812 -- added warning about cyclic imports in contrib.comments. Thanks to Beetle_B, bjourne and philgyford for the reports, and Russ for the wording.

Backport of r14810 from trunk.

git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.2.X@14811 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 12 insertions, 0 deletions

diff --git a/docs/ref/contrib/comments/custom.txt b/docs/ref/contrib/comments/custom.txt
index 49299d4d33..5411d9ce70 100644
--- a/docs/ref/contrib/comments/custom.txt
+++ b/docs/ref/contrib/comments/custom.txt
@@ -110,6 +110,18 @@ point Django at these classes we've created::
     def get_form():
         return CommentFormWithTitle
 
+
+.. warning::
+
+    Be careful not to create cyclic imports in your custom comments app.
+    If you feel your comment configuration isn't being used as defined --
+    for example, if your comment moderation policy isn't being applied --
+    you may have a cyclic import problem.
+
+    If you are having unexplained problems with comments behavior, check
+    if your custom comments application imports (even indirectly)
+    any module that itself imports Django's comments module.
+
 The above process should take care of most common situations. For more
 advanced usage, there are additional methods you can define. Those are
 explained in the next section.