Update the deprecation decorator towards SemVer

qiskit/utils/deprecation.py

@@ -27,7 +27,7 @@ def deprecate_func(
     additional_msg: str | None = None,
     pending: bool = False,
     package_name: str = "Qiskit",
-    removal_timeline: str = "no earlier than 3 months after the release date",
+    removal_timeline: str | None = None,
     is_property: bool = False,
     stacklevel: int = 2,
 ):
@@ -47,7 +47,8 @@ def deprecate_func(
         pending: Set to ``True`` if the deprecation is still pending.
         package_name: The package name shown in the deprecation message (e.g. the PyPI package name).
         removal_timeline: How soon can this deprecation be removed? Expects a value
-            like "no sooner than 6 months after the latest release" or "in release 9.99".
+            like "in two major releases" or "in release 9.99". Default:
+            "in the next major release {since_major + 1}".
         is_property: If the deprecated function is a `@property`, set this to True so that the
             generated message correctly describes it as such. (This isn't necessary for
             property setters, as their docstring is ignored by Python.)
@@ -112,7 +113,7 @@ def deprecate_arg(
     package_name: str = "Qiskit",
     new_alias: str | None = None,
     predicate: Callable[[Any], bool] | None = None,
-    removal_timeline: str = "no earlier than 3 months after the release date",
+    removal_timeline: str | None = None,
 ):
     """Decorator to indicate an argument has been deprecated in some way.
 
@@ -139,7 +140,8 @@ def deprecate_arg(
             `lambda my_arg: isinstance(my_arg, dict)`. Regardless of if a predicate is set, the
             runtime warning will only log when the user specifies the argument.
         removal_timeline: How soon can this deprecation be removed? Expects a value
-            like "no sooner than 6 months after the latest release" or "in release 9.99".
+            like "in two major releases" or "in release 9.99". Default:
+            "in the next major release {since_major + 1}".
 
     Returns:
         Callable: The decorated callable.
@@ -246,8 +248,12 @@ def _write_deprecation_msg(
     since: str,
     pending: bool,
     additional_msg: str,
-    removal_timeline: str,
+    removal_timeline: str | None,
 ) -> tuple[str, Type[DeprecationWarning] | Type[PendingDeprecationWarning]]:
+    if not removal_timeline:
+        removal_major = int(str(since).split(".", maxsplit=1)[0]) + 1
+        removal_timeline = f"in the next major release {removal_major}.0"
+
     if pending:
         category: Type[DeprecationWarning] | Type[PendingDeprecationWarning] = (
             PendingDeprecationWarning

releasenotes/notes/semver_deprecation-6b0f07db27dfc638.yaml

@@ -0,0 +1,7 @@
+---
+upgrade_misc:
+  - |
+    The decorators :func:`deprecate_func` and :func:`deprecate_arg` changed their default behaivor to adapt to the
+    Qiskit SemVer versioning (`RFC0020` <https://github.com/Qiskit/qiskit/issues/8729>`__). As a consequence,
+    the parameter ``removal_timeline`` default changed: from "no earlier than 3 months after the release date" to "in the next major
+    release {``since`` major + 1}". If you would like to preserve the previous messaging, you should set ``removal_timeline`` explicitly.

test/python/utils/test_deprecation.py

@@ -83,8 +83,7 @@ def test_deprecate_func_docstring(self) -> None:
 
                 .. deprecated:: 9.99_pending
                   The class ``{__name__}._Foo`` is pending deprecation as of Qiskit 9.99. It \
-will be marked deprecated in a future release, and then removed no earlier than 3 months after \
-the release date.
+will be marked deprecated in a future release, and then removed in the next major release 10.0.
                 """
             ),
         )
@@ -96,7 +95,7 @@ def test_deprecate_func_docstring(self) -> None:
 
                 .. deprecated:: 9.99
                   The method ``{__name__}._Foo.my_method()`` is deprecated as of Qiskit \
-9.99. It will be removed no earlier than 3 months after the release date. Stop using this!
+9.99. It will be removed in the next major release 10.0. Stop using this!
                 """
             ),
         )
@@ -108,7 +107,7 @@ def test_deprecate_func_docstring(self) -> None:
 
                 .. deprecated:: 9.99
                   The property ``{__name__}._Foo.my_property`` is deprecated as of Qiskit \
-9.99. It will be removed no earlier than 3 months after the release date.
+9.99. It will be removed in the next major release 10.0.
                 """
             ),
         )
@@ -152,18 +151,18 @@ def my_func() -> None:
 
                 .. deprecated:: 9.99
                   ``{__name__}.{my_func.__qualname__}()``'s argument ``arg4`` is deprecated as of \
-Qiskit 9.99. It will be removed no earlier than 3 months after the release date. Instead, \
+Qiskit 9.99. It will be removed in the next major release 10.0. Instead, \
 use foo.
 
                 .. deprecated:: 9.99
                   Using the argument arg3 is deprecated as of Qiskit 9.99. It will be \
-removed no earlier than 3 months after the release date. Instead, use the argument ``new_arg3``, \
+removed in the next major release 10.0. Instead, use the argument ``new_arg3``, \
 which behaves identically.
 
                 .. deprecated:: 9.99_pending
                   ``{__name__}.{my_func.__qualname__}()``'s argument ``arg2`` is pending \
 deprecation as of Qiskit 9.99. It will be marked deprecated in a future release, and then \
-removed no earlier than 3 months after the release date.
+removed in the next major release 10.0.
 
                 .. deprecated:: 9.99
                   ``{__name__}.{my_func.__qualname__}()``'s argument ``arg1`` is deprecated as of \