[0.46] Update the deprecation decorator towards SemVer

[1ucian0]

This is the stable/0.46 version of #11296 (as merigify didnt do what I was expecting).

---

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

[jakelishman]

Mergify's just waiting for the base PR to merge before it opened a backport. It might be best to wait for it to do that, just so we can be sure we get all the changes synced between the branches.

[mtreinish]

Based on my review comments on #11296 I don't think this PR is eligible for 0.46.0. It introduces an API change to the behavior of the decorator (as the default behavior changes) as this is a public interface and downstream libraries are actively using it. 0.46.0 is supposed to be fully compatible with 0.45.x and this would break that messaging. We could do it as a new feature add, where None is an explicitly new type allowed for the decorator but the default message still shows the previous default message. But then that would require updating all the decorator usage in the repo. Given that 0.46.0 is supposed to be released today I've just untagged this from the 0.46.0 milestone

[1ucian0]

0.46 is close to end-of-life. Closing this one.