Doc'd RemovedInDjangoXXWarning comments in deprecating a feature guide.

1 files changed, 25 insertions, 1 deletions

diff --git a/docs/internals/contributing/writing-code/submitting-patches.txt b/docs/internals/contributing/writing-code/submitting-patches.txt
index 8ef5c1da54..59c17ce9a3 100644
--- a/docs/internals/contributing/writing-code/submitting-patches.txt
+++ b/docs/internals/contributing/writing-code/submitting-patches.txt
@@ -201,7 +201,7 @@ level:
     class MyDeprecatedTests(unittest.TestCase):
         ...
 
-You can also add a test for the deprecation warning::
+You should also add a test for the deprecation warning::
 
     from django.utils.deprecation import RemovedInDjangoXXWarning
 
@@ -212,6 +212,30 @@ You can also add a test for the deprecation warning::
             # invoke deprecated behavior
             ...
 
+It's important to include a ``RemovedInDjangoXXWarning`` comment above code
+which has no warning reference, but will need to be changed or removed when the
+deprecation ends. This could include hooks which have been added to keep the
+previous behavior, or standalone items that are unnecessary or unused when the
+deprecation ends. For example::
+
+    import warnings
+    from django.utils.deprecation import RemovedInDjangoXXWarning
+
+
+    # RemovedInDjangoXXWarning.
+    def old_private_helper():
+        # Helper function that is only used in foo().
+        pass
+
+
+    def foo():
+        warnings.warn(
+            "foo() is deprecated.",
+            category=RemovedInDjangoXXWarning,
+        )
+        old_private_helper()
+        ...
+
 Finally, there are a couple of updates to Django's documentation to make:
 
 #) If the existing feature is documented, mark it deprecated in documentation