[4.2.x] Doc'd RemovedInDjangoXXWarning comments in deprecating a feature guide.

Backport of 1611a3af1c from main
This commit is contained in:
Sarah Boyce 2023-04-19 13:47:27 +02:00 committed by Natalia
parent 7679741c46
commit df44c7b3cc
1 changed files with 25 additions and 1 deletions

View File

@ -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