Update the deprecation decorator towards SemVer

[1ucian0]

The current deprecate decorators extend the docstring with the following:

I suggest the following to be aligned with Qiskit/documentation#366

[qiskit-bot]

One or more of the the following people are requested to review this:

• @Qiskit/terra-core

[mtreinish]

This works fine, but we should have sufficient info to compute the next major version from the since field. We could set this to None and then do something like:

if removal_timeline is None:
    removal_major = int(since.split(",")[0]) + 1
    removal_timeline = f"in the next major release {removal_major}"

Or if you're worried about deprecated features passing a major version boundary (e.g. we deprecate something in 1.0 and don't remove it until 3.0) we can replace since with the package's __version__.

[1ucian0]

good one! Done in cd47576

However, replacing since with __version__ might be tricky. If a features was deprecated in 1.1.0, we want to keep that since after the release of 1.2.0. Or am I missing something?

[coveralls]

Pull Request Test Coverage Report for Build 7716377393

Warning: This coverage report may be inaccurate.

We've detected an issue with your CI configuration that might affect the accuracy of this pull request's coverage report.
To ensure accuracy in future PRs, please see these guidelines.
A quick fix for this PR: rebase it; your next report should be accurate.

• 0 of 3 (100.0%) changed or added relevant lines in 1 file are covered.
• 841 unchanged lines in 74 files lost coverage.
• Overall coverage increased (+0.1%) to 89.457%

---

Files with Coverage Reduction	New Missed Lines	%
crates/accelerate/src/sabre_swap/mod.rs	1	97.42%
qiskit/circuit/classical/types/ordering.py	1	94.64%
qiskit/circuit/controlflow/control_flow.py	1	92.86%
qiskit/circuit/library/standard_gates/global_phase.py	1	95.83%
qiskit/circuit/library/standard_gates/rx.py	1	98.55%
qiskit/circuit/library/standard_gates/ry.py	1	98.51%
qiskit/circuit/library/standard_gates/ryy.py	1	97.3%
qiskit/circuit/library/standard_gates/rz.py	1	98.46%
qiskit/circuit/library/standard_gates/rzz.py	1	97.06%
qiskit/circuit/library/standard_gates/swap.py	1	98.08%

Totals
Change from base Build 7508541254:	0.1%
Covered Lines:	59550
Relevant Lines:	66568

---

💛 - Coveralls

[1ucian0]

@Mergifyio backport stable/0.46

[mergify]

backport stable/0.46

🟠 Waiting for conditions to match

• merged [📌 backport requirement]

[mtreinish]

As weird as this is to ask for on a deprecation decorator, I think this needs a release note as this is a public documented function and we're adding a new option and changing the default behavior. It will need a feature release note and an upgrade note as existing users who don't set removal_timeline will get different messages after upgrading qiskit.

[mtreinish]

Given that rc1 is supposed to go out today, I'm going to defer this to 1.1. We'll have to rework this PR to not be a breaking api change for 1.1, but I think that's manageable.