135 lines
8.0 KiB
Plaintext
135 lines
8.0 KiB
Plaintext
---
|
|
title: Qiskit SDK version strategy
|
|
description: Details on the Qiskit SDK versioning strategy, release schedule, upgrade strategy, pre-releases, post-releases, and how contributors can mark deprecations.
|
|
---
|
|
|
|
# Qiskit SDK version strategy
|
|
|
|
Qiskit version numbers follow [Semantic Versioning](https://semver.org/).
|
|
The version number is comprised of three primary components: the major, minor, and
|
|
patch versions. For example, in version number `X.Y.Z`, `X` is the major version,
|
|
`Y` is the minor version, and `Z` is the patch version.
|
|
|
|
Breaking API changes are reserved for major version releases. The **minimum**
|
|
period between major version releases is one year. Minor versions introduce
|
|
new features and bug fixes without breaking API compatibility, and are
|
|
periodically (currently every three months) published for **only** the
|
|
current major version. Patch versions provide fixes for bugs identified in
|
|
the most recent minor version of each actively supported release series (that is, the
|
|
major version). We support at most two release series at a time, which occurs
|
|
only during the period of overlap following a new major version release,
|
|
described in more detail below.
|
|
|
|
|
|
## Release schedule
|
|
|
|
|
|
A tentative release schedule is included below:
|
|
|
|
|
|
|
|
For an up-to-date release schedule, refer to the Qiskit Github project's [milestones list](https://github.com/Qiskit/qiskit/milestones), which will always contain the current release plan.
|
|
|
|
With the release of a new major version, the previous major version is supported
|
|
for at least six months; only bug and security fixes are accepted during this time and only patch releases are published for this major version. A final
|
|
patch version is published when support is dropped, and that release
|
|
also documents the end of support for that major version series. A longer
|
|
support window is needed for the previous major version as this gives downstream
|
|
Qiskit consumers and their users a chance to migrate their code.
|
|
Downstream libraries that
|
|
depend on Qiskit should not raise their minimum required Qiskit version to a new
|
|
major version immediately after its release because the library's user base needs time
|
|
to migrate to the new API changes. Having an extended support window
|
|
for the previous major Qiskit version gives downstream projects time to ensure
|
|
compatibility with the next major version. Downstream projects can provide
|
|
support for two release series at a time to give their users a migration path.
|
|
|
|
For the purposes of semantic versioning, the Qiskit public API is considered
|
|
any documented module, class, function, or method that is not marked as private
|
|
(with an underscore `_` prefix). However, there can be explicit exceptions made for
|
|
specific documented APIs. In such cases, these APIs will be clearly documented
|
|
as not being considered stable interfaces yet, and a user-visible warning will be
|
|
actively emitted on any use of these unstable interfaces. Additionally, in some
|
|
situations, an interface marked as private is considered part of the public
|
|
API. Typically this only occurs in two cases: either an abstract interface
|
|
definition where subclasses are intended to override/implement a private method
|
|
as part of defining an implementation of the interface, or advanced-usage
|
|
low-level methods that have stable interfaces but are not considered safe to use,
|
|
as the burden is on the user to uphold the class/safety invariants themselves
|
|
(the canonical example of this is the `QuantumCircuit._append` method).
|
|
|
|
The supported Python versions, minimum supported Rust version (for building
|
|
Qiskit from source), and any Python package dependencies (including the minimum
|
|
supported versions of dependencies) used by Qiskit are not part of the backwards
|
|
compatibility guarantees and may change during any release. Only minor or major
|
|
version releases will raise minimum requirements for using or building Qiskit
|
|
(including adding new dependencies), but patch fixes might include support for
|
|
new versions of Python or other dependencies. Usually the minimum version of a
|
|
dependency is only increased when older dependency versions go out of support or
|
|
when it is not possible to maintain compatibility with the latest release of the
|
|
dependency and the older version.
|
|
|
|
## Upgrade strategy
|
|
|
|
When a new major version is released, the recommended upgrade path
|
|
is to first upgrade to the most recent minor version on the previous major
|
|
version. Shortly before a new major version, a final minor version will
|
|
be published. This final minor version release `X.Y+1.0.0` is equivalent to
|
|
`X.Y.0` but with warnings and deprecations for any API changes that are
|
|
made on the new major version series.
|
|
|
|
For example, immediately proceeding the 1.0.0 release, a 0.46.0 release will be
|
|
published. The 0.46.0 release will be equivalent to the 0.45.0 release but with
|
|
additional deprecation warnings that document the API changes that were made as
|
|
part of the 1.0.0 release. This pattern will be used for any future major
|
|
version releases.
|
|
|
|
Qiskit users should first upgrade to this final minor
|
|
version to see any deprecation warnings and adjust their Qiskit
|
|
usage before trying a potentially breaking release. The previous
|
|
major version will be supported for at least six months to give sufficient time
|
|
to upgrade. A typical pattern to manage this is to pin the maximum version to
|
|
avoid using the next major release series until you're sure of compatibility.
|
|
For example, specifying `qiskit<2` in a requirements file when the current
|
|
major Qiskit version is 1 ensures that you're using a version of Qiskit
|
|
that doesn't have breaking API changes.
|
|
|
|
Capping the version less than the next major version
|
|
ensures that you see any deprecation warnings before a
|
|
major version release.
|
|
Without the cap, `pip` installs
|
|
the newest version available by default.
|
|
|
|
The QPY serialization format is backwards-compatible so that a new Qiskit release can always load a QPY
|
|
file generated with an earlier release of Qiskit. However, the format isn't forward-compatible so, in principle, it's not possible
|
|
to load QPY files generated with a newer version of Qiskit using an older release. To facilitate user migration across major version releases, the [`qiskit.qpy.dump()`](/api/qiskit/qpy#dump) function will always support at least one overlapping version between the `X.0.0` and the `X-1.Y.0` release (where `Y` is the last minor version of
|
|
that series). The parameter `qiskit.qpy.dump(..., version=...)` will enable saving QPY format files that can be loaded by both major versions from the newer
|
|
release. See more details in [RFC 0020](https://github.com/Qiskit/RFCs/blob/master/0020-release_cycle.md#qpy-support).
|
|
|
|
## Pre-releases
|
|
|
|
For each minor and major version release, Qiskit publishes pre-releases that
|
|
are compatible with [PEP440](https://peps.python.org/pep-0440/). Typically
|
|
these are release candidates of the form `X.Y.0rc1`. The `rc` releases
|
|
will have a finalized API surface and are used to test a prospective release.
|
|
|
|
Note that when one of the PEP440 pre-release suffixes (such as `a`, `b`, or `pre`) are
|
|
published, it does not have the same guarantees as an `rc` release, and is
|
|
only a preview release. The API might change between these pre-releases
|
|
and the final release with that version number. For example, `1.0.0pre1` might have
|
|
a different final API than `1.0.0`.
|
|
|
|
|
|
## Post-releases
|
|
|
|
If there are issues with a release's packaging, a post-release might be
|
|
issued to correct this. These will follow the form `X.Y.Z.1` where the fourth
|
|
integer indicates that it is the first post-release of the `X.Y.Z` release.
|
|
For example, the qiskit-terra (the legacy package name for Qiskit) 0.25.2
|
|
release had some issue with the sdist package publishing, and a post-release
|
|
0.25.2.1 was published that corrected this issue. The code was identical, and
|
|
0.25.2.1 only fixed the packaging issue for the release.
|
|
|
|
## How contributors can mark deprecations
|
|
|
|
Refer to the [deprecation guide](https://github.com/Qiskit/qiskit/blob/main/DEPRECATION.md) in the Qiskit SDK repository for instructions on how to add deprecations to the source code. |