Clarify how to handle pending deprecations

Qiskit · Feb 23, 2023 · 08a07a7 · 08a07a7
1 parent a43e4a1
commit 08a07a7
Showing 1 changed file with 6 additions and 2 deletions.
diff --git a/qiskit/utils/deprecation.py b/qiskit/utils/deprecation.py
@@ -29,7 +29,9 @@ def deprecate_arguments(
         kwarg_map: A dictionary of the old argument name to the new name.
         category: Usually either DeprecationWarning or PendingDeprecationWarning.
         since: The version the deprecation started at. Only Optional for backwards
-            compatibility - this should always be set.
+            compatibility - this should always be set. If the deprecation is pending, set
+            the version to when that started; but later, when switching from pending to
+            deprecated, update `since` to the new version.
 
     Returns:
         Callable: The decorated callable.
@@ -63,7 +65,9 @@ def deprecate_function(
         stacklevel: The warning stacklevel to use, defaults to 2.
         category: Usually either DeprecationWarning or PendingDeprecationWarning.
         since: The version the deprecation started at. Only Optional for backwards
-            compatibility - this should always be set.
+            compatibility - this should always be set. If the deprecation is pending, set
+            the version to when that started; but later, when switching from pending to
+            deprecated, update `since` to the new version.
 
     Returns:
         Callable: The decorated, deprecated callable.