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,
 ):
     """Decorator to indicate a function has been deprecated.
@@ -46,7 +46,8 @@ def deprecate_func(
         pending: Set to ``True`` if the deprecation is still pending.
         package_name: The PyPI package name, e.g. "qiskit-nature".
         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.)
@@ -111,7 +112,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.
 
@@ -138,7 +139,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.
@@ -353,8 +355,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(since.split(".")[0]) + 1
+        removal_timeline = f"in the next major release {removal_major}.0"
+
     if pending:
         category: Type[DeprecationWarning] | Type[
             PendingDeprecationWarning

test/python/utils/test_deprecation.py

@@ -84,8 +84,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.
                 """
             ),
         )
@@ -97,7 +96,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!
                 """
             ),
         )
@@ -109,7 +108,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.
                 """
             ),
         )
@@ -143,18 +142,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 \