Skip to content

Update deprecation policy document for Qiskit 1.0 #11775

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mtreinish merged 3 commits into from
Feb 15, 2024
Merged

Update deprecation policy document for Qiskit 1.0 #11775

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
23cbfb0
Update deprecation policy document for Qiskit 1.0
jakelishman Feb 12, 2024
a7aaa44
Commit to raising a warning on experimental features
jakelishman Feb 12, 2024
8c6c560
Remove comment on internal import policy
jakelishman Feb 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 56 additions & 26 deletions DEPRECATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,12 @@
# Deprecation Policy

Starting from the 1.0.0 release, Qiskit follows semantic versioning, with a yearly release cycle for major releases.
[Full details of the scheduling are hosted with the external public documentation](https://docs.quantum.ibm.com/start/install#release-schedule).

This document is primarily intended for developers of Qiskit themselves.

## Principles

Many users and other packages depend on different parts of Qiskit. We must
make sure that whenever we make changes to the code, we give users ample time to
adjust without breaking code that they have already written.
Expand All @@ -19,55 +26,76 @@ underscore (`_`).

The guiding principles are:

- we must not remove or change code without active warnings for least three
months or two complete version cycles;
- removals or behavior changes in the public API can only occur in major releases;

- new deprecations to the public API can only occur in minor releases;

- there must always be a way to achieve valid goals that does not issue any
warnings;
warnings with the most recent two minor releases in a series;

- never assume that an object that is part of the public interface is not in use.

While the no-breaking-changes rule is only formally required *within* a major release series, you should make every effort to avoid breaking changes wherever possible.
Similarly, while it is permissible where necessary for behavior to change with no single-code path to support both the last minor of one major release and the first minor of a new major release, it is still strongly preferable if you can achieve this.
Copy link
Copy Markdown
Contributor

@jlapeyre jlapeyre Feb 13, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this should be single code path. For example two-code path doesn't make sense but two code paths does.

Copy link
Copy Markdown
Member Author

@jakelishman jakelishman Feb 13, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I using the hyphen to make it so that in your example, the plural would have been "two-codes path", as in "the direction which requires two codes" - "path" wasn't meant in the sense of "codepath" but "direction". Happier for better wording, though.

Copy link
Copy Markdown
Contributor

@jlapeyre jlapeyre Feb 13, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That does make sense. single code path in the sense of "sequence of instructions" does not in this context. But I wasn't able to find that meaning.

Copy link
Copy Markdown
Contributor

@jlapeyre jlapeyre Feb 13, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm struggling a bit to get the precise meaning of this

behavior [to] change with no single-code path to support both the last minor of one major release and the first minor of a new major release

  • So single-code path means a solution such that the user has one chunk of code that they don't need to alter between the two versions?
  • Does behavior change here refer to a change in behavior without a change in API? In other words, a user runs code in version A. Then in version B, the same code runs but gives different results.
  • Suppose the answer to these questions is "yes" (and say the dev insists on maintaining both) Then I don't see a way to turn this into a non-breaking change.

Copy link
Copy Markdown
Member

@mtreinish mtreinish Feb 14, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, in my reading this is describing the situation of 0.46 ->1.0 where we introduced a deprecation warning in 0.46 and removed that api in 1.0. This is a breaking change and because it's for a new major version this is allowed. This is basically just saying, that while the policy allows us to to do with the major version bump, it's preferable to try and maintain compatibility if possible.

Copy link
Copy Markdown
Member Author

@jakelishman jakelishman Feb 14, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, that's what I was going for: "you're technically allowed to make changes that don't have a single way that works on both 0.x and 1.0, but really try not to do that". If there's better wording people want, I'm happy to update.



## What is the public interface?

- never assume that a function that isn't explicitly internal isn't in use;
> [!NOTE]
> This section should be in sync with [the release schedule documentation of Qiskit](https://docs.quantum.ibm.com/start/install#release-schedule).
> Please [open an issue against Qiskit](https://github.com/Qiskit/qiskit/issues/new/choose) if there are discrepancies so we can clarify them.

- all deprecations, changes and removals are considered API changes, and can
only occur in minor releases not patch releases, per the [stable branch policy](https://github.com/Qiskit/qiskit/blob/main/MAINTAINING.md#stable-branch-policy).
For the purposes of semantic versioning, the Qiskit public API comprises all *publicly documented* packages, modules, classes, functions, methods, and attributes.

An object is *publicly documented* if and only if it appears in [the hosted API documentation](https://docs.quantum.ibm.com/api/qiskit) for Qiskit.
The presence of a docstring in the Python source (or a `__doc__` attribute) is not sufficient to make an object publicly documented; this documentation must also be rendered in the public API documentation.

As well as the objects themselves needing to be publicly documented, the only public-API *import locations* for a given object is the location it is documented at in [the public API documentation](https://docs.quantum.ibm.com/api/qiskit), and parent modules or packages that re-export the object (if any).
For example, while it is possible to import `Measure` from `qiskit.circuit.measure`, this is not a supported part of the public API for two reasons:

1. The module `qiskit.circuit.measure` is not publicly documented, so is not part of the public interface.
2. The [`Measure` object is documented as being in `qiskit.circuit.library`](https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.library.Measure), and is re-exported by `qiskit.circuit`, so the public import paths are `from qiskit.circuit.library import Measure` and `from qiskit.circuit import Measure`.

As a rule of thumb, if you are using Qiskit, you should import objects from the highest-level package that exports that object.
Copy link
Copy Markdown
Member

@mtreinish mtreinish Feb 12, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This does raise some questions about things like QuantumCircuit and transpile which are re-exported from the root qiskit import, but are documented in qiskit.circuit and qiskit.compiler respectively.

Copy link
Copy Markdown
Member Author

@jakelishman jakelishman Feb 12, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd roughly attempted to address that with bullet point 2. Are you thinking we need to write more in the public version of the policy / do more in the documentation / something else?

Copy link
Copy Markdown
Member

@mtreinish mtreinish Feb 12, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TBH, it's more just a discrepancy I hadn't thought of before. More specifically I'm wondering if this points to a deficiency in our documentation more than anything else, should we be documenting the public API as qiskit.QuantumCircuit or qiskit.circuit.QuantumCircuit and yeah the extension for that for the user facing component of the stability policy which is considered the stable access point. In my head it's both, but I'm wondering how to express that cleanly.

Copy link
Copy Markdown
Member Author

@jakelishman jakelishman Feb 12, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I'd say the public interface is that QuantumCircuit is available from both qiskit and qiskit.circuit. In an ideal world, we'd specify __all__ fields on all the public modules/packages of the API, and then document those, and that would define all the public API import locations. We can't actually write that in the policy right now, though, because we don't actually do it, so I guess maybe we have to use these slightly fuzzy heuristics.


Some components of the documented public interface may be marked as "experimental", and not subject to the stability guarantees of semantic versioning.
These will be clearly denoted in the documentation, and will raise an `ExperimentalWarning` when used.
We will only use these "experimental" features sparingly, when we feel there is a real benefit to making the experimental version public in an unstable form, such as a backwards-incompatible new version of core functionality that shows significant improvements over the existing form for limited inputs, but is not yet fully feature complete.
Typically, a feature will only become part of the public API when we are ready to commit to its stability properly.


## Removing a feature

> [!IMPORTANT]
> Features can only be removed in new major versions.
> Deprecations can only be added in new minor versions.

When removing a feature (for example a class, function or function parameter),
we will follow this procedure:

- The alternative path must be in place for one minor version before any
warnings are issued. For example, if we want to replace the function `foo()`
with `bar()`, we must make at least one release with both functions before
with `bar()`, we must make at least one minor release with both functions before
issuing any warnings within `foo()`. You may issue
`PendingDeprecationWarning`s from the old paths immediately.
`PendingDeprecationWarning`s from the old paths immediately, but this is not
necessary and does not affect any timelines for removal.

*Reason*: we need to give people time to swap over without breaking their
code as soon as they upgrade.
*Reason*: we need to give people time to swap over without breaking their
code as soon as they upgrade.

- After the alternative path has been in place for at least one minor version,
[issue the deprecation warnings](#issuing-deprecation-warnings). Add a
release note with a `deprecations` section listing all deprecated paths,
their alternatives, and the reason for deprecation. [Update the tests to test the warnings](#testing-deprecated-functionality).

*Reason*: removals must be highly visible for at least one version, to
minimize the surprise to users when they actually go.

- Set a removal date for the old feature, and remove it (and the warnings) when
reached. This must be at least three months after the version with the
warnings was first released, and cannot be the minor version immediately
after the warnings. Add an `upgrade` release note that lists all the
removals. For example, if the alternative path was provided in `0.19.0`
and the warnings were added in `0.20.0`, the earliest version for removal
is `0.22.0`, even if `0.21.0` was released more than three months after
`0.20.0`.
*Reason*: removals must be highly visible for at least one version, to
minimize the surprise to users when they actually go.

**Note: These are _minimum_** requirements. For removal of significant or core features, give
users at least an extra minor version if not longer.**
- Apply the removal to the branch for the next major release, or open an issue to remind us to effect the removal and tag it for the milestone of the next major release.

*Reason*: there needs to be time for users to see these messages, and to give
them time to adjust. Not all users will update their version of Qiskit
immediately, and some may skip minor versions.
> [!NOTE]
> These are _minimum_ requirements.
> For removal of significant or core features, try to give as long a warning period as is feasible.

When a feature is marked as deprecated it is slated for removal, but users
should still be able to rely on it to work correctly. We consider a feature
Expand All @@ -77,6 +105,8 @@ fixes until it is removed, but we won't merge new functionality to it.

## Changing behavior

> [!IMPORTANT]
> Breaking behavior changes can only occur in new major versions, and should be avoided as much as possible.

Changing behavior without a removal is particularly difficult to manage, because
we need to have both options available for two versions, and be able to issue
Expand Down