0.6 release notes and deprecation policy (qiskit-community#1385)

### Summary

Update the release notes and deprecation policy prior to release.

---------

Co-authored-by: Will Shanks <wshaos@posteo.net>

CONTRIBUTING.md

@@ -74,7 +74,7 @@ When submitting a pull request for review, please ensure that:
    etc.), you've added or updated a reno release note for that change and tagged the PR
    for the changelog.
 6. If your code requires a change to dependencies, you've updated the corresponding
-   requirements file: `requirements.txt` contain core dependencies,
+   requirements file: `requirements.txt` for core dependencies,
    `requirements-extras.txt` for dependencies for optional features, and `requirements-dev.txt`
    for dependencies required for running tests and building documentation.
 
@@ -361,11 +361,48 @@ There are a few other build options available:
 
 ### Deprecation policy
 
-Qiskit Experiments is part of Qiskit and, therefore, the [Qiskit Deprecation
-Policy](https://github.com/Qiskit/qiskit/blob/main/DEPRECATION.md) fully applies here.
-Public-facing changes must come with a deprecation warning for at least three months or
-two version cycles before the old feature is removed. Deprecations can only happen on
-minor releases and not on patch releases.
+Any change to the existing package code that affects how the user interacts with the package
+should give the user clear instructions and advanced warning if the change is nontrivial.
+Qiskit Experiments's deprecation policy is based on [Qiskit's
+policy](https://github.com/Qiskit/qiskit/blob/1.0.0rc1/DEPRECATION.md) prior to its 1.0 release, but
+we impose less stringent requirements such that developers can iterate more quickly.
+Deprecations and feature removals can only happen on minor releases and not on patch releases.
+
+The deprecation policy depends on the significance of the user-facing change, which we have divided into
+three categories:
+
+A **core feature change** is one that affects how the framework functions, for example a
+change to `BaseExperiment`. The timeline for deprecating an existing core feature is as follows:
+
+* Minor release 1: An alternative path is provided. A `PendingDeprecationWarning` 
+  should be issued when the old path is used, indicating to users how to switch to
+  the new path and the release in which the old path will no longer be available. The
+  developer may choose to directly deprecate the feature and issue a `DeprecationWarning` instead,
+  in which case the release note should indicate the feature has been deprecated and how to switch
+  to the new path.
+* Minor release 2: The `PendingDeprecationWarning` becomes a `DeprecationWarning`, or the
+  `DeprecationWarning` remains in place. The release note should indicate the feature has
+  been deprecated and how to switch to the new path.
+* Minor release 3: The old feature is removed. The release note should indicate that the feature has
+  been removed and how to switch to the new path.
+
+If the three-release cycle takes fewer than three months, the feature removal must wait for more
+releases until three months has elapsed since the first issuing of the `PendingDeprecationWarning`
+or `DeprecationWarning`.
+
+A **non-core feature change** may be a change to a specific experiment class or modules such as the
+plotter. The timeline is shortened for such a change:
+
+* Minor release 1: An alternative path is provided. A `DeprecationWarning` should be issued
+  when the old path is used, indicating to users how to switch to the new path and the release
+  in which the old path will no longer be available.
+* Minor release 2: The old feature is removed. The release note should indicate that the feature has
+  been removed and how to switch to the new path.
+
+Lastly, a **minor, non-core change** could be a cosmetic change such as output file names or a
+change to helper functions that isn't directly used in the package codebase. These can be made in
+one release without a deprecation process as long as the change is clearly described in the
+release notes.
 
 #### Adding deprecation warnings
 
@@ -379,6 +416,7 @@ Utilities](https://docs.quantum.ibm.com/api/qiskit/utils) to add warnings:
   @deprecate_func(
       since="0.5",
       additional_msg="Use ``new_function`` instead.",
+      pending=True,
       removal_timeline="after 0.7",
       package_name="qiskit-experiments",
   )
@@ -389,6 +427,12 @@ Utilities](https://docs.quantum.ibm.com/api/qiskit/utils) to add warnings:
       pass
 ```
 
+Note that all warnings emitted by Qiskit Experiments, including pre-deprecation and deprecation
+warnings, will cause the CI to fail, but features up for deprecation should continue to be tested
+until their removal. For more information on how to use wrappers and test deprecated functionality,
+consult [Qiskit's
+policy](https://github.com/Qiskit/qiskit/blob/1.0.0rc1/DEPRECATION.md#issuing-deprecation-warnings).
+
 ### Development cycle
 
 The development cycle for Qiskit Experiments is all handled in the open using project

docs/conf.py

@@ -173,6 +173,7 @@
     "qiskit_aer": ("https://qiskit.org/ecosystem/aer", None),
     "qiskit_dynamics": ("https://qiskit.org/ecosystem/dynamics/", None),
     "qiskit_ibm_runtime": ("https://docs.quantum.ibm.com/api/qiskit-ibm-runtime/", None),
+    "qiskit_ibm_provider": ("https://docs.quantum.ibm.com/api/qiskit-ibm-provider/", None),
 }
 
 

docs/howtos/cloud_service.rst

@@ -18,8 +18,8 @@ Saving
 ~~~~~~
 
 .. note::
-    This guide requires :mod:`qiskit-ibm-runtime` version 0.15 and up, which can be installed with ``python -m pip install qiskit-ibm-runtime``.
-    For how to migrate from the older :mod:`qiskit-ibm-provider` to :mod:`qiskit-ibm-runtime`,
+    This guide requires :external+qiskit_ibm_runtime:doc:`qiskit-ibm-runtime <index>` version 0.15 and up, which can be installed with ``python -m pip install qiskit-ibm-runtime``.
+    For how to migrate from the older :external+qiskit_ibm_provider:doc:`qiskit-ibm-provider <index>` to :external+qiskit_ibm_runtime:doc:`qiskit-ibm-runtime <index>`,
     consult the `migration guide <https://docs.quantum.ibm.com/api/migration-guides/qiskit-runtime-from-provider>`_.\
 
 You must run the experiment on a real IBM

docs/howtos/rerun_analysis.rst

@@ -12,8 +12,8 @@ Solution
 --------
 
 .. note::
-    This guide requires :mod:`qiskit-ibm-runtime` version 0.15 and up, which can be installed with ``python -m pip install qiskit-ibm-runtime``.
-    For how to migrate from the older :mod:`qiskit-ibm-provider` to :mod:`qiskit-ibm-runtime`,
+    This guide requires :external+qiskit_ibm_runtime:doc:`qiskit-ibm-runtime <index>` version 0.15 and up, which can be installed with ``python -m pip install qiskit-ibm-runtime``.
+    For how to migrate from the older :external+qiskit_ibm_provider:doc:`qiskit-ibm-provider <index>` to :external+qiskit_ibm_runtime:doc:`qiskit-ibm-runtime <index>`,
     consult the `migration guide <https://docs.quantum.ibm.com/api/migration-guides/qiskit-runtime-from-provider>`_.\
 
 Once you recreate the exact experiment you ran and all of its parameters and options,

docs/howtos/runtime_sessions.rst

@@ -11,11 +11,11 @@ Solution
 --------
 
 .. note::
-    This guide requires :mod:`qiskit-ibm-runtime` version 0.15 and up, which can be installed with ``python -m pip install qiskit-ibm-runtime``.
-    For how to migrate from the older :mod:`qiskit-ibm-provider` to :mod:`qiskit-ibm-runtime`,
+    This guide requires :external+qiskit_ibm_runtime:doc:`qiskit-ibm-runtime <index>` version 0.15 and up, which can be installed with ``python -m pip install qiskit-ibm-runtime``.
+    For how to migrate from the older :external+qiskit_ibm_provider:doc:`qiskit-ibm-provider <index>` to :external+qiskit_ibm_runtime:doc:`qiskit-ibm-runtime <index>`,
     consult the `migration guide <https://docs.quantum.ibm.com/api/migration-guides/qiskit-runtime-from-provider>`_.\
 
-Use the :class:`~qiskit_ibm_runtime.IBMBackend` object in :mod:`qiskit-ibm-runtime`, which supports sessions.
+Use the :class:`~qiskit_ibm_runtime.IBMBackend` object in :external+qiskit_ibm_runtime:doc:`index`, which supports sessions.
 
 In this example, we will set the ``max_circuits`` property to an artificially low value so that the experiment will be
 split into multiple jobs that run sequentially in a single session. When running real experiments with a

docs/manuals/characterization/stark_experiment.rst

@@ -113,7 +113,7 @@ In a typical IBM device using the cross-resonance drive architecture,
 such channel can be identified with your backend as follows:
 
 .. note::
-    This tutorial requires the :mod:`qiskit_ibm_runtime` package to model a
+    This tutorial requires the :external+qiskit_ibm_runtime:doc:`qiskit-ibm-runtime <index>` package to model a
     backend.  You can install it with ``python -m pip install qiskit-ibm-runtime``.
 
 .. jupyter-execute::

docs/manuals/characterization/t1.rst

@@ -30,7 +30,7 @@ The following code demonstrates a basic run of a :math:`T_1` experiment
 for qubit 0.
 
 .. note::
-    This tutorial requires the :mod:`qiskit_aer` and :mod:`qiskit_ibm_runtime`
+    This tutorial requires the :external+qiskit_aer:doc:`qiskit-aer <index>` and :external+qiskit_ibm_runtime:doc:`qiskit-ibm-runtime <index>`
     packages to run simulations.  You can install them with ``python -m pip
     install qiskit-aer qiskit-ibm-runtime``.
 

docs/manuals/characterization/t2ramsey.rst

@@ -58,7 +58,7 @@ We run the experiment on a simulated backend using Qiskit Aer with a
 pure T1/T2 relaxation noise model.
 
 .. note::
-    This tutorial requires the :mod:`qiskit_aer` and :mod:`qiskit_ibm_runtime`
+    This tutorial requires the :external+qiskit_aer:doc:`qiskit-aer <index>` and :external+qiskit_ibm_runtime:doc:`qiskit-ibm-runtime <index>`
     packages to run simulations.  You can install them with ``python -m pip
     install qiskit-aer qiskit-ibm-runtime``.
 

docs/manuals/characterization/tphi.rst

@@ -21,7 +21,7 @@ From the :math:`T_1` and :math:`T_2` estimates, we compute the results for
 :math:`T_\varphi.`
 
 .. note::
-    This tutorial requires the :mod:`qiskit_aer` and :mod:`qiskit_ibm_runtime`
+    This tutorial requires the :external+qiskit_aer:doc:`qiskit-aer <index>` and :external+qiskit_ibm_runtime:doc:`qiskit-ibm-runtime <index>`
     packages to run simulations.  You can install them with ``python -m pip
     install qiskit-aer qiskit-ibm-runtime``.
 

docs/manuals/measurement/readout_mitigation.rst

@@ -31,7 +31,7 @@ This notebook demonstrates the usage of both the local and correlated
 experiments to generate the corresponding mitigators.
 
 .. note::
-    This tutorial requires the :mod:`qiskit_aer` and :mod:`qiskit_ibm_runtime`
+    This tutorial requires the :external+qiskit_aer:doc:`qiskit-aer <index>` and :external+qiskit_ibm_runtime:doc:`qiskit-ibm-runtime <index>`
     packages to run simulations.  You can install them with ``python -m pip
     install qiskit-aer qiskit-ibm-runtime``.
 

docs/manuals/measurement/restless_measurements.rst

@@ -59,7 +59,7 @@ observe any meaningful outcomes with fake backends since the circuit simulator
 they use always starts with the qubits in the ground state.
 
 .. note::
-    This tutorial requires the :mod:`qiskit_ibm_runtime` package to model a
+    This tutorial requires the :external+qiskit_ibm_runtime:doc:`qiskit-ibm-runtime <index>` package to model a
     backend.  You can install it with ``python -m pip install qiskit-ibm-runtime``.
 
 .. jupyter-execute::

docs/manuals/verification/quantum_volume.rst

@@ -25,7 +25,7 @@ probability` > 2/3 with confidence level > 0.977 (corresponding to
 z_value = 2), and at least 100 trials have been ran.
 
 .. note::
-    This tutorial requires the :mod:`qiskit_aer` and :mod:`qiskit_ibm_runtime`
+    This tutorial requires the :external+qiskit_aer:doc:`qiskit-aer <index>` and :external+qiskit_ibm_runtime:doc:`qiskit-ibm-runtime <index>`
     packages to run simulations.  You can install them with ``python -m pip
     install qiskit-aer qiskit-ibm-runtime``.
 

docs/manuals/verification/randomized_benchmarking.rst

@@ -12,7 +12,7 @@ error estimates for the quantum device, by calculating the Error Per Clifford. S
 explanation on the RB method, which is based on Refs. [1]_ [2]_.
 
 .. note::
-    This tutorial requires the :mod:`qiskit_aer` and :mod:`qiskit_ibm_runtime`
+    This tutorial requires the :external+qiskit_aer:doc:`qiskit-aer <index>` and :external+qiskit_ibm_runtime:doc:`qiskit-ibm-runtime <index>`
     packages to run simulations.  You can install them with ``python -m pip
     install qiskit-aer qiskit-ibm-runtime``.
 

docs/manuals/verification/state_tomography.rst

@@ -8,7 +8,7 @@ of a quantum state by preparing the state many times and measuring them in a tom
 complete basis of measurement operators.
 
 .. note::
-    This tutorial requires the :mod:`qiskit_aer` and :mod:`qiskit_ibm_runtime`
+    This tutorial requires the :external+qiskit_aer:doc:`qiskit-aer <index>` and :external+qiskit_ibm_runtime:doc:`qiskit-ibm-runtime <index>`
     packages to run simulations.  You can install them with ``python -m pip
     install qiskit-aer qiskit-ibm-runtime``.
 

docs/tutorials/custom_experiment.rst

@@ -558,7 +558,7 @@ output if the Pauli corresponding to that bit has a nonzero signature.
 To test our code, we first simulate a noisy backend with asymmetric readout error.
 
 .. note::
-    This tutorial requires the :mod:`qiskit_aer` package for simulations.
+    This tutorial requires the :external+qiskit_aer:doc:`qiskit-aer <index>` package for simulations.
     You can install it with ``python -m pip install qiskit-aer``.
 
 

docs/tutorials/getting_started.rst

@@ -41,6 +41,30 @@ cloning the repository:
 The ``-e`` option will keep your installed package up to date as you make or pull new
 changes.
 
+Upgrading Qiskit Experiments
+----------------------------
+
+Qiskit Experiments version numbers are in the form ``0.X.Y``, where ``X`` is the minor version and
+``Y`` is the patch version. There are two kinds of releases: minor releases, which increment the
+minor version, and patch releases, which increment the patch version. New features and API
+changes can only be introduced in a minor release. Patch releases contain only bug fixes and changes that do
+not affect how you use the package, such as performance optimization and documentation updates.
+
+Therefore, when you encounter a bug or unexpected behavior, it is recommended that you first check if there's a
+patch release you can upgrade to under the same minor version to avoid any breaking changes. When
+running ``pip``, you can specify the exact version to install:
+
+.. code-block::
+
+    python -m pip install qiskit-experiments==0.X.Y
+
+Before a nontrivial breaking API change is introduced in a minor release, the old feature will
+undergo a deprecation process lasting two releases for a core framework change and one release
+otherwise. During this process, deprecation warnings will be issued if you use the old feature that
+will instruct you on how to transition to the replacement feature, if applicable. The :doc:`release
+notes </release_notes>` contain full details on which features are deprecated or removed in each
+release.
+
 Running your first experiment
 =============================
 
@@ -58,7 +82,7 @@ Experiments must be run on a backend. We're going to use a simulator,
 backend, real or simulated, that you can access through Qiskit.
 
 .. note::
-    This tutorial requires the :mod:`qiskit_aer` and :mod:`qiskit_ibm_runtime`
+    This tutorial requires the :external+qiskit_aer:doc:`qiskit-aer <index>` and :external+qiskit_ibm_runtime:doc:`qiskit-ibm-runtime <index>`
     packages to run simulations.  You can install them with ``python -m pip
     install qiskit-aer qiskit-ibm-runtime``.
 
@@ -73,11 +97,6 @@ All experiments require a ``physical_qubits`` parameter as input that specifies
 physical qubit or qubits the circuits will be executed on. The qubits must be given as a
 Python sequence (usually a tuple or a list).
 
-.. note::
-    Since 0.5.0, using ``qubits`` instead of ``physical_qubits`` or specifying an
-    integer qubit index instead of a one-element sequence for a single-qubit experiment
-    is deprecated.
-
 In addition, the :math:`T_1` experiment has
 a second required parameter, ``delays``, which is a list of times in seconds at which to
 measure the excited state population. In this example, we'll run the :math:`T_1`

docs/tutorials/visualization.rst

@@ -34,8 +34,8 @@ Generating and customizing a figure using a plotter
 First, we display the default figure from a :class:`.Rabi` experiment as a starting point:
 
 .. note::
-    This tutorial requires the :mod:`qiskit_dynamics`, :mod:`qiskit_aer`, and
-    :mod:`qiskit_ibm_runtime` packages to run simulations.  You can install them
+    This tutorial requires the :mod:`qiskit_dynamics`, :external+qiskit_aer:doc:`qiskit-aer <index>`, and
+    :external+qiskit_ibm_runtime:doc:`qiskit-ibm-runtime <index>` packages to run simulations.  You can install them
     with ``python -m pip install qiskit-dynamics qiskit-aer qiskit-ibm-runtime``.
 
 .. jupyter-execute::

qiskit_experiments/data_processing/nodes.py

@@ -740,9 +740,9 @@ def __init__(
 
         Args:
             outcome: The bitstring for which to return the probability and variance.
-            alpha_prior: A prior Beta distribution parameter ``[`alpha0, alpha1]``.
+            alpha_prior: A prior Beta distribution parameter ``[alpha0, alpha1]``.
                          If specified as float this will use the same value for
-                         ``alpha0`` and``alpha1`` (Default: 0.5).
+                         ``alpha0`` and ``alpha1`` (Default: 0.5).
             validate: If set to False the DataAction will not validate its input.
 
         Raises:

qiskit_experiments/framework/experiment_data.py

@@ -2271,9 +2271,11 @@ def load(
             experiment_id: Experiment ID.
             service: the database service.
             provider: an IBMProvider required for loading job data and
-                can be used to initialize the service. In ``qiskit-ibm-runtime``,
-                this is the ``QiskitRuntimeService`` and should not be confused with
-                the experiment database service.
+                can be used to initialize the service. When using
+                :external+qiskit_ibm_runtime:doc:`qiskit-ibm-runtime <index>`,
+                this is the :class:`~qiskit_ibm_runtime.QiskitRuntimeService` and should
+                not be confused with the experiment database service
+                :meth:`qiskit_ibm_experiment.IBMExperimentService`.
 
         Returns:
             The loaded experiment data.

qiskit_experiments/library/calibration/half_angle_cal.py

@@ -28,7 +28,7 @@
 
 
 class HalfAngleCal(BaseCalibrationExperiment, HalfAngle):
-    """Calibration version of the half-angle experiment."""
+    """Calibration version of the :class:`.HalfAngle` experiment."""
 
     def __init__(
         self,

qiskit_experiments/library/quantum_volume/qv_experiment.py

@@ -88,7 +88,7 @@ def __init__(
             simulation_backend: The simulator backend to use to generate
                 the expected results. the simulator must have a 'save_probabilities'
                 method. If None, the :class:`qiskit_aer.AerSimulator` simulator will be used
-                (in case :mod:`qiskit_aer` is not
+                (in case :external+qiskit_aer:doc:`qiskit-aer <index>` is not
                 installed, :class:`qiskit.quantum_info.Statevector` will be used).
         """
         super().__init__(physical_qubits, analysis=QuantumVolumeAnalysis(), backend=backend)

qiskit_experiments/library/randomized_benchmarking/__init__.py

@@ -37,6 +37,14 @@
     RBAnalysis
     InterleavedRBAnalysis
 
+Synthesis
+=========
+
+.. autosummary::
+    :toctree: ../stubs/
+
+    RBDefaultCliffordSynthesis
+
 Utilities
 =========
 
@@ -52,3 +60,4 @@
 from .interleaved_rb_analysis import InterleavedRBAnalysis
 from .clifford_utils import CliffordUtils
 from .rb_utils import RBUtils
+from .clifford_synthesis import RBDefaultCliffordSynthesis

qiskit_experiments/library/randomized_benchmarking/clifford_synthesis.py

@@ -60,7 +60,7 @@ def run(
 
         Returns:
             The quantum circuit representation of the Operation
-                when successful, and ``None`` otherwise.
+            when successful, and ``None`` otherwise.
 
         Raises:
             QiskitError: If basis_gates is not supplied.