From df44c7b3cc66e0eadd44e794f31e66ccbb385bac Mon Sep 17 00:00:00 2001
From: Sarah Boyce <42296566+sarahboyce@users.noreply.github.com>
Date: Wed, 19 Apr 2023 13:47:27 +0200
Subject: [PATCH] [4.2.x] Doc'd RemovedInDjangoXXWarning comments in
 deprecating a feature guide.

Backport of 1611a3af1cf18256db389f259a020414ec1226b4 from main
---
 .../writing-code/submitting-patches.txt       | 26 ++++++++++++++++++-
 1 file changed, 25 insertions(+), 1 deletion(-)

diff --git a/docs/internals/contributing/writing-code/submitting-patches.txt b/docs/internals/contributing/writing-code/submitting-patches.txt
index 8ef5c1da548..59c17ce9a38 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