Browse Source

Doc'd RemovedInDjangoXXWarning comments in deprecating a feature guide.

Sarah Boyce 1 year ago
parent
commit
1611a3af1c
1 changed files with 25 additions and 1 deletions
  1. 25 1
      docs/internals/contributing/writing-code/submitting-patches.txt

+ 25 - 1
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