From 77481cdb208e5e8343ca4350f23b9d32aebb6069 Mon Sep 17 00:00:00 2001 From: Matthew Treinish Date: Thu, 16 Nov 2023 12:55:28 -0500 Subject: [PATCH 01/18] Document Qiskit versioning and stability policy This commit adds a new document to the hosted documentation for Qiskit's versioning and stability policy. This is a continuation of Qiskit/qiskit#11205 which documents for Qiskit users the versioning and stability policy for the library. It includes an explanation of how to interpret version numbers, the tentative release schedule for the project, as well as a definition of what interfaces are considered stable. This outlines the minimum support windows for major versions and how deprecations and breaking changes will work with regards to versioning. This documentation is critical to include with the Qiskit 1.0.0 release as it establishes the expectations around the major version release for users (all previous documentation on the subject tactically avoided the discussion of a major version). --- docs/start/qiskit-versioning.mdx | 126 +++++++++++++++++++++++ public/images/start/release_schedule.png | Bin 0 -> 34176 bytes 2 files changed, 126 insertions(+) create mode 100644 docs/start/qiskit-versioning.mdx create mode 100644 public/images/start/release_schedule.png diff --git a/docs/start/qiskit-versioning.mdx b/docs/start/qiskit-versioning.mdx new file mode 100644 index 00000000000..2ee7f40608b --- /dev/null +++ b/docs/start/qiskit-versioning.mdx @@ -0,0 +1,126 @@ +--- +title: Qiskit Versioning and Support Policy +description: The versioning and support policy for Qiskit. + +--- + +# Qiskit Versioning +Qiskit version numbers follow [Semantic Versioning](https://semver.org/). +The version number is comprised of 3 primary components, the major, minor, and +patch versions. For a version number `X.Y.Z` where `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 will be +periodically (currently every three months) published for the current major +version which add new features and bug fixes. For the most recent minor version +there will also be new patch versions published as bugs are identified and fixed +on that release series. A tentative release schedule is included below: + +![timeline.png](../../public/images/timeline.png) + +For an up-to-date release schedule you should 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 6 months; only bug and security fixes will be accepted during this +time and only patch releases will be published for this major version. A final +patch version will be published when support is dropped and that release will +also document the end of support for that major version series. A longer +support window is needed for the previous major version as this gives downstream +consumers of Qiskit a chance to migrate not only their code but also their +users. It's typically not recommended for a downstream library that +depends on Qiskit to bump its minimum Qiskit version to a new +major version release immediately because its user base also needs a chance +to migrate to the new API changes. Having an extended support window +for the previous major Qiskit version gives downstream projects time to fix +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 a `_` prefix). However, there can be explicit exceptions made in the case +of specific documented APIs. In such cases these will be clearly documented as +either not being considered stable interfaces yet and a warning will be actively +emitted on the use of these unstable interface. In some situations an interface +marked as private will be considered part of the public API, these +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 + +Whenever a new major version is released the recommended upgrade path +is to first upgrade to use the most recent minor version on the previous major +version. Immediately preceding a new major version a final minor version will +be published. This final minor version release `M.N+1.0` is equivalent to +`M.N.0` but with warnings and deprecations for any API changes that are +made on the new major version series. + +For example, on the release of Qiskit 1.0.0 a 0.46.0 release was published +immediately proceeding the 1.0.0 release. The 0.46.0 release was 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. + +As a user of Qiskit it's recommended that you first upgrade to this final minor +version first, so you can see any deprecation warnings and adjust your Qiskit +usage ahead of time before trying a potentially breaking release. The previous +major version will be supported for at least 6 months to give sufficient time +to upgrade. A typical pattern to deal with this is to pin the max version to +avoid using the next major release series until you're sure of compatibility. +For example, specifying in a requirements file `qiskit<2` when the current +major Qiskit version is 1 will ensure that you're using a version of Qiskit +that won't have breaking API changes. + +Pre-emptively capping the version less than the next major version is neccessary +to ensure you get a chance to see deprecation warnings before a +major version release. The normal release schedule means the last minor +version release which includes any final deprecation warnings will be released +at the same time as the next major version and `pip` will default to using +the newest version available unless the version cap is set. + + +## Pre-releases + +For each minor and major version release Qiskit will publish pre-releases that +are compatible with `PEP440 `__. Typically +these are just release candidates of the form `1.2.0rc1`. The `rc` releases +will have a finalized API surface and are used to test a prospective release. + +If another PEP440 pre-release suffix (such as `a`, `b`, or `pre`) are +published these do not have the same guarantees as an `rc` release, and are +just preview releases. The API likely will change between these pre-releases +and the final release with that version number. For example, `1.0.0pre1` has +a different final API from `1.0.0`. + + +## Post-releases + +If there are issues with the packaging of a given release a post-release may be +issued to correct this. These will follow the form `1.2.1.1` where the fourth +integer is used to indicate it is the 1st post release of the `1.2.1` 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 just fixed the packaging issue for the release. diff --git a/public/images/start/release_schedule.png b/public/images/start/release_schedule.png new file mode 100644 index 0000000000000000000000000000000000000000..f89fbe4923915eb67ddb160330fb0a1ee32be106 GIT binary patch literal 34176 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 Date: Thu, 16 Nov 2023 13:19:36 -0500 Subject: [PATCH 02/18] Fix spelling lint --- cSpell.json | 3 ++- docs/start/qiskit-versioning.mdx | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/cSpell.json b/cSpell.json index 10d0d647218..c43afc45bd9 100644 --- a/cSpell.json +++ b/cSpell.json @@ -247,7 +247,8 @@ "mathrm", "exponentiated", "simulable", - "resynthesizes" + "resynthesizes", + "sdist" ], "ignoreRegExpList": [ // Markdown links diff --git a/docs/start/qiskit-versioning.mdx b/docs/start/qiskit-versioning.mdx index 2ee7f40608b..9eac02705bf 100644 --- a/docs/start/qiskit-versioning.mdx +++ b/docs/start/qiskit-versioning.mdx @@ -93,7 +93,7 @@ For example, specifying in a requirements file `qiskit<2` when the current major Qiskit version is 1 will ensure that you're using a version of Qiskit that won't have breaking API changes. -Pre-emptively capping the version less than the next major version is neccessary +Pre-emptively capping the version less than the next major version is necessary to ensure you get a chance to see deprecation warnings before a major version release. The normal release schedule means the last minor version release which includes any final deprecation warnings will be released From 7482b50a84a03cfdb1a39c31f8354d83d3ab4da3 Mon Sep 17 00:00:00 2001 From: Matthew Treinish Date: Thu, 16 Nov 2023 13:21:29 -0500 Subject: [PATCH 03/18] Fix image link --- docs/start/qiskit-versioning.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/start/qiskit-versioning.mdx b/docs/start/qiskit-versioning.mdx index 9eac02705bf..5702ddb9421 100644 --- a/docs/start/qiskit-versioning.mdx +++ b/docs/start/qiskit-versioning.mdx @@ -17,7 +17,7 @@ version which add new features and bug fixes. For the most recent minor version there will also be new patch versions published as bugs are identified and fixed on that release series. A tentative release schedule is included below: -![timeline.png](../../public/images/timeline.png) +![timeline.png](public/images/start/release_schedule.png) For an up-to-date release schedule you should refer to the Qiskit Github project's [milestones list](https://github.com/Qiskit/qiskit/milestones) which will always From d1926d972f9b504288f8e209a4b6e81531b1c860 Mon Sep 17 00:00:00 2001 From: Matthew Treinish Date: Thu, 16 Nov 2023 13:42:51 -0500 Subject: [PATCH 04/18] Apply suggestions from code review Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> --- docs/start/qiskit-versioning.mdx | 19 ++++++------------- 1 file changed, 6 insertions(+), 13 deletions(-) diff --git a/docs/start/qiskit-versioning.mdx b/docs/start/qiskit-versioning.mdx index 5702ddb9421..e1a16791d06 100644 --- a/docs/start/qiskit-versioning.mdx +++ b/docs/start/qiskit-versioning.mdx @@ -3,7 +3,6 @@ title: Qiskit Versioning and Support Policy description: The versioning and support policy for Qiskit. --- - # Qiskit Versioning Qiskit version numbers follow [Semantic Versioning](https://semver.org/). The version number is comprised of 3 primary components, the major, minor, and @@ -13,14 +12,14 @@ patch versions. For a version number `X.Y.Z` where `X` is the major version, Breaking API changes are reserved for major version releases. The **minimum** period between major version releases is one year. Minor versions will be periodically (currently every three months) published for the current major -version which add new features and bug fixes. For the most recent minor version +version which add new features and bug fixes. For the most recent minor version, there will also be new patch versions published as bugs are identified and fixed on that release series. A tentative release schedule is included below: ![timeline.png](public/images/start/release_schedule.png) For an up-to-date release schedule you should refer to the Qiskit Github project's -[milestones list](https://github.com/Qiskit/qiskit/milestones) which will always +[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 @@ -39,9 +38,6 @@ 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 a `_` prefix). However, there can be explicit exceptions made in the case @@ -67,23 +63,22 @@ 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 -Whenever a new major version is released the recommended upgrade path +Whenever a new major version is released, the recommended upgrade path is to first upgrade to use the most recent minor version on the previous major version. Immediately preceding a new major version a final minor version will be published. This final minor version release `M.N+1.0` is equivalent to `M.N.0` but with warnings and deprecations for any API changes that are made on the new major version series. -For example, on the release of Qiskit 1.0.0 a 0.46.0 release was published +For example, on the release of Qiskit 1.0.0, a 0.46.0 release was published immediately proceeding the 1.0.0 release. The 0.46.0 release was 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. -As a user of Qiskit it's recommended that you first upgrade to this final minor +As a user of Qiskit, it's recommended that you first upgrade to this final minor version first, so you can see any deprecation warnings and adjust your Qiskit usage ahead of time before trying a potentially breaking release. The previous major version will be supported for at least 6 months to give sufficient time @@ -100,11 +95,10 @@ version release which includes any final deprecation warnings will be released at the same time as the next major version and `pip` will default to using the newest version available unless the version cap is set. - ## Pre-releases For each minor and major version release Qiskit will publish pre-releases that -are compatible with `PEP440 `__. Typically +are compatible with [PEP440](https://peps.python.org/pep-0440/). Typically these are just release candidates of the form `1.2.0rc1`. The `rc` releases will have a finalized API surface and are used to test a prospective release. @@ -114,7 +108,6 @@ just preview releases. The API likely will change between these pre-releases and the final release with that version number. For example, `1.0.0pre1` has a different final API from `1.0.0`. - ## Post-releases If there are issues with the packaging of a given release a post-release may be From 7d522c3392a86111f6b438ddfe15f1ec155342da Mon Sep 17 00:00:00 2001 From: Matthew Treinish Date: Thu, 16 Nov 2023 13:45:38 -0500 Subject: [PATCH 05/18] Update image link path --- docs/start/qiskit-versioning.mdx | 2 +- .../{ => qiskit-versioning}/release_schedule.png | Bin 2 files changed, 1 insertion(+), 1 deletion(-) rename public/images/start/{ => qiskit-versioning}/release_schedule.png (100%) diff --git a/docs/start/qiskit-versioning.mdx b/docs/start/qiskit-versioning.mdx index e1a16791d06..99a7aa07266 100644 --- a/docs/start/qiskit-versioning.mdx +++ b/docs/start/qiskit-versioning.mdx @@ -16,7 +16,7 @@ version which add new features and bug fixes. For the most recent minor version, there will also be new patch versions published as bugs are identified and fixed on that release series. A tentative release schedule is included below: -![timeline.png](public/images/start/release_schedule.png) +![timeline.png](/images/release_schedule.png) For an up-to-date release schedule you should refer to the Qiskit Github project's [milestones list](https://github.com/Qiskit/qiskit/milestones), which will always diff --git a/public/images/start/release_schedule.png b/public/images/start/qiskit-versioning/release_schedule.png similarity index 100% rename from public/images/start/release_schedule.png rename to public/images/start/qiskit-versioning/release_schedule.png From 2a48e8ee0a769dd242319f53cee13d67fd72a058 Mon Sep 17 00:00:00 2001 From: Matthew Treinish Date: Thu, 16 Nov 2023 13:47:20 -0500 Subject: [PATCH 06/18] Add to the toc --- docs/start/_toc.json | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/start/_toc.json b/docs/start/_toc.json index 1634b60ab98..a41cac70e7d 100644 --- a/docs/start/_toc.json +++ b/docs/start/_toc.json @@ -35,6 +35,10 @@ "url": "/start/configure-qiskit-local" } ] + }, + { + "title": "Qiskit Versioning", + "url": "/start/qiskit-versioning" } ] } From fa8b7db95bb2c549f858c8ff5c8aee7c8763f349 Mon Sep 17 00:00:00 2001 From: Matthew Treinish Date: Thu, 16 Nov 2023 13:58:14 -0500 Subject: [PATCH 07/18] Really fix image link --- docs/start/qiskit-versioning.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/start/qiskit-versioning.mdx b/docs/start/qiskit-versioning.mdx index 99a7aa07266..56524f4eaea 100644 --- a/docs/start/qiskit-versioning.mdx +++ b/docs/start/qiskit-versioning.mdx @@ -16,7 +16,7 @@ version which add new features and bug fixes. For the most recent minor version, there will also be new patch versions published as bugs are identified and fixed on that release series. A tentative release schedule is included below: -![timeline.png](/images/release_schedule.png) +![](/images/qiskit-versioning/release_schedule.png) For an up-to-date release schedule you should refer to the Qiskit Github project's [milestones list](https://github.com/Qiskit/qiskit/milestones), which will always From b58790a07c32d0aa63780b5bde6ae8882903b8fc Mon Sep 17 00:00:00 2001 From: Matthew Treinish Date: Thu, 16 Nov 2023 14:38:08 -0500 Subject: [PATCH 08/18] Update docs/start/qiskit-versioning.mdx Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> --- docs/start/qiskit-versioning.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/start/qiskit-versioning.mdx b/docs/start/qiskit-versioning.mdx index 56524f4eaea..0deb0e58481 100644 --- a/docs/start/qiskit-versioning.mdx +++ b/docs/start/qiskit-versioning.mdx @@ -16,7 +16,7 @@ version which add new features and bug fixes. For the most recent minor version, there will also be new patch versions published as bugs are identified and fixed on that release series. A tentative release schedule is included below: -![](/images/qiskit-versioning/release_schedule.png) +![](/images/start/qiskit-versioning/release_schedule.png) For an up-to-date release schedule you should refer to the Qiskit Github project's [milestones list](https://github.com/Qiskit/qiskit/milestones), which will always From c2ba71045b70f0de4123dde664025557d592b929 Mon Sep 17 00:00:00 2001 From: Matthew Treinish Date: Mon, 20 Nov 2023 15:28:38 -0500 Subject: [PATCH 09/18] Move document into install page --- docs/start/install.mdx | 117 ++++++++++++++++- docs/start/qiskit-versioning.mdx | 119 ------------------ .../release_schedule.png | Bin 3 files changed, 115 insertions(+), 121 deletions(-) delete mode 100644 docs/start/qiskit-versioning.mdx rename public/images/start/{qiskit-versioning => install}/release_schedule.png (100%) diff --git a/docs/start/install.mdx b/docs/start/install.mdx index 13240120a3b..80478f55ea0 100644 --- a/docs/start/install.mdx +++ b/docs/start/install.mdx @@ -128,6 +128,119 @@ Tier 3 operating systems: - Linux i686 (distributions compatible with the [manylinux 2014](https://www.python.org/dev/peps/pep-0599/) packaging specification) for Python 3.10 or later - Windows 32 bit for Python 3.10 or later +## Qiskit Versioning +Qiskit version numbers follow [Semantic Versioning](https://semver.org/). +The version number is comprised of 3 primary components, the major, minor, and +patch versions. For a version number `X.Y.Z` where `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 will be +periodically (currently every three months) published for the current major +version which add new features and bug fixes. For the most recent minor version, +there will also be new patch versions published as bugs are identified and fixed +on that release series. A tentative release schedule is included below: + +![](/images/start/install/release_schedule.png) + +For an up-to-date release schedule you should 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 6 months; only bug and security fixes will be accepted during this +time and only patch releases will be published for this major version. A final +patch version will be published when support is dropped and that release will +also document the end of support for that major version series. A longer +support window is needed for the previous major version as this gives downstream +consumers of Qiskit a chance to migrate not only their code but also their +users. It's typically not recommended for a downstream library that +depends on Qiskit to bump its minimum Qiskit version to a new +major version release immediately because its user base also needs a chance +to migrate to the new API changes. Having an extended support window +for the previous major Qiskit version gives downstream projects time to fix +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 a `_` prefix). However, there can be explicit exceptions made in the case +of specific documented APIs. In such cases these will be clearly documented as +either not being considered stable interfaces yet and a warning will be actively +emitted on the use of these unstable interface. In some situations an interface +marked as private will be considered part of the public API, these +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 + +Whenever a new major version is released, the recommended upgrade path +is to first upgrade to use the most recent minor version on the previous major +version. Immediately preceding a new major version a final minor version will +be published. This final minor version release `M.N+1.0` is equivalent to +`M.N.0` but with warnings and deprecations for any API changes that are +made on the new major version series. + +For example, on the release of Qiskit 1.0.0, a 0.46.0 release was published +immediately proceeding the 1.0.0 release. The 0.46.0 release was 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. + +As a user of Qiskit, it's recommended that you first upgrade to this final minor +version first, so you can see any deprecation warnings and adjust your Qiskit +usage ahead of time before trying a potentially breaking release. The previous +major version will be supported for at least 6 months to give sufficient time +to upgrade. A typical pattern to deal with this is to pin the max version to +avoid using the next major release series until you're sure of compatibility. +For example, specifying in a requirements file `qiskit<2` when the current +major Qiskit version is 1 will ensure that you're using a version of Qiskit +that won't have breaking API changes. + +Pre-emptively capping the version less than the next major version is necessary +to ensure you get a chance to see deprecation warnings before a +major version release. The normal release schedule means the last minor +version release which includes any final deprecation warnings will be released +at the same time as the next major version and `pip` will default to using +the newest version available unless the version cap is set. + +### Pre-releases + +For each minor and major version release Qiskit will publish pre-releases that +are compatible with [PEP440](https://peps.python.org/pep-0440/). Typically +these are just release candidates of the form `1.2.0rc1`. The `rc` releases +will have a finalized API surface and are used to test a prospective release. + +If another PEP440 pre-release suffix (such as `a`, `b`, or `pre`) are +published these do not have the same guarantees as an `rc` release, and are +just preview releases. The API likely will change between these pre-releases +and the final release with that version number. For example, `1.0.0pre1` has +a different final API from `1.0.0`. + +### Post-releases + +If there are issues with the packaging of a given release a post-release may be +issued to correct this. These will follow the form `1.2.1.1` where the fourth +integer is used to indicate it is the 1st post release of the `1.2.1` 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 just fixed the packaging issue for the release. ## Troubleshooting @@ -175,11 +288,11 @@ please check the documentation of the package that failed to install (in the example code, ``SOME_PACKAGE``) for information on how to install the libraries needed for compiling from source. - ## Next steps - [Select and set up an IBM Quantum channel.](setup-channel) - [Configure Qiskit locally.](configure-qiskit-local) - Follow the steps in [Hello world](hello-world) to write and run a quantum program. - \ No newline at end of file + + diff --git a/docs/start/qiskit-versioning.mdx b/docs/start/qiskit-versioning.mdx deleted file mode 100644 index 0deb0e58481..00000000000 --- a/docs/start/qiskit-versioning.mdx +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: Qiskit Versioning and Support Policy -description: The versioning and support policy for Qiskit. - ---- -# Qiskit Versioning -Qiskit version numbers follow [Semantic Versioning](https://semver.org/). -The version number is comprised of 3 primary components, the major, minor, and -patch versions. For a version number `X.Y.Z` where `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 will be -periodically (currently every three months) published for the current major -version which add new features and bug fixes. For the most recent minor version, -there will also be new patch versions published as bugs are identified and fixed -on that release series. A tentative release schedule is included below: - -![](/images/start/qiskit-versioning/release_schedule.png) - -For an up-to-date release schedule you should 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 6 months; only bug and security fixes will be accepted during this -time and only patch releases will be published for this major version. A final -patch version will be published when support is dropped and that release will -also document the end of support for that major version series. A longer -support window is needed for the previous major version as this gives downstream -consumers of Qiskit a chance to migrate not only their code but also their -users. It's typically not recommended for a downstream library that -depends on Qiskit to bump its minimum Qiskit version to a new -major version release immediately because its user base also needs a chance -to migrate to the new API changes. Having an extended support window -for the previous major Qiskit version gives downstream projects time to fix -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 a `_` prefix). However, there can be explicit exceptions made in the case -of specific documented APIs. In such cases these will be clearly documented as -either not being considered stable interfaces yet and a warning will be actively -emitted on the use of these unstable interface. In some situations an interface -marked as private will be considered part of the public API, these -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 - -Whenever a new major version is released, the recommended upgrade path -is to first upgrade to use the most recent minor version on the previous major -version. Immediately preceding a new major version a final minor version will -be published. This final minor version release `M.N+1.0` is equivalent to -`M.N.0` but with warnings and deprecations for any API changes that are -made on the new major version series. - -For example, on the release of Qiskit 1.0.0, a 0.46.0 release was published -immediately proceeding the 1.0.0 release. The 0.46.0 release was 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. - -As a user of Qiskit, it's recommended that you first upgrade to this final minor -version first, so you can see any deprecation warnings and adjust your Qiskit -usage ahead of time before trying a potentially breaking release. The previous -major version will be supported for at least 6 months to give sufficient time -to upgrade. A typical pattern to deal with this is to pin the max version to -avoid using the next major release series until you're sure of compatibility. -For example, specifying in a requirements file `qiskit<2` when the current -major Qiskit version is 1 will ensure that you're using a version of Qiskit -that won't have breaking API changes. - -Pre-emptively capping the version less than the next major version is necessary -to ensure you get a chance to see deprecation warnings before a -major version release. The normal release schedule means the last minor -version release which includes any final deprecation warnings will be released -at the same time as the next major version and `pip` will default to using -the newest version available unless the version cap is set. - -## Pre-releases - -For each minor and major version release Qiskit will publish pre-releases that -are compatible with [PEP440](https://peps.python.org/pep-0440/). Typically -these are just release candidates of the form `1.2.0rc1`. The `rc` releases -will have a finalized API surface and are used to test a prospective release. - -If another PEP440 pre-release suffix (such as `a`, `b`, or `pre`) are -published these do not have the same guarantees as an `rc` release, and are -just preview releases. The API likely will change between these pre-releases -and the final release with that version number. For example, `1.0.0pre1` has -a different final API from `1.0.0`. - -## Post-releases - -If there are issues with the packaging of a given release a post-release may be -issued to correct this. These will follow the form `1.2.1.1` where the fourth -integer is used to indicate it is the 1st post release of the `1.2.1` 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 just fixed the packaging issue for the release. diff --git a/public/images/start/qiskit-versioning/release_schedule.png b/public/images/start/install/release_schedule.png similarity index 100% rename from public/images/start/qiskit-versioning/release_schedule.png rename to public/images/start/install/release_schedule.png From ac12590257dcb763c016b223e07faa779a8bd1ae Mon Sep 17 00:00:00 2001 From: Matthew Treinish Date: Mon, 20 Nov 2023 15:52:40 -0500 Subject: [PATCH 10/18] Update wording of public api surface --- docs/start/install.mdx | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/start/install.mdx b/docs/start/install.mdx index 80478f55ea0..5547faf2c80 100644 --- a/docs/start/install.mdx +++ b/docs/start/install.mdx @@ -129,6 +129,7 @@ Tier 3 operating systems: - Windows 32 bit for Python 3.10 or later ## Qiskit Versioning + Qiskit version numbers follow [Semantic Versioning](https://semver.org/). The version number is comprised of 3 primary components, the major, minor, and patch versions. For a version number `X.Y.Z` where `X` is the major version, @@ -165,16 +166,16 @@ 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 a `_` prefix). However, there can be explicit exceptions made in the case -of specific documented APIs. In such cases these will be clearly documented as -either not being considered stable interfaces yet and a warning will be actively -emitted on the use of these unstable interface. In some situations an interface -marked as private will be considered part of the public API, these -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) +of 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 will be 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 From 8472c60f924427a5dc6b31c8ba40ac0f693e7c26 Mon Sep 17 00:00:00 2001 From: Matthew Treinish Date: Mon, 20 Nov 2023 15:56:00 -0500 Subject: [PATCH 11/18] Remove stray newline --- docs/start/install.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/start/install.mdx b/docs/start/install.mdx index 3d24086c1c1..88aec99df1c 100644 --- a/docs/start/install.mdx +++ b/docs/start/install.mdx @@ -310,4 +310,3 @@ release had some issue with the sdist package publishing and a post-release - [Configure Qiskit locally.](configure-qiskit-local) - Follow the steps in [Hello world](hello-world) to write and run a quantum program. - From 15b2e651c5d564cdd0211eacd460365a2c9fa843 Mon Sep 17 00:00:00 2001 From: Matthew Treinish Date: Mon, 20 Nov 2023 15:58:28 -0500 Subject: [PATCH 12/18] Adjust tense around qiskit 1.0.0 release The doc was originally written under the assumption it would be published as part of Qiskit 1.0.0 on qiskit.org/documentation (with a dev build available with the 1.0.0pre1 release). However since we intend this to be published for real with the pre release this adjusts the tense around the 1.0.0 release to indicate it's coming out in the future. Everything in this guide is still valid prior to the 1.0.0 release because it just documents the versioning and stability guidelines moving forward and still apply to 0.45.x (the current release series). --- docs/start/install.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/start/install.mdx b/docs/start/install.mdx index 88aec99df1c..5b6f6d4941e 100644 --- a/docs/start/install.mdx +++ b/docs/start/install.mdx @@ -206,11 +206,11 @@ be published. This final minor version release `M.N+1.0` is equivalent to `M.N.0` but with warnings and deprecations for any API changes that are made on the new major version series. -For example, on the release of Qiskit 1.0.0, a 0.46.0 release was published -immediately proceeding the 1.0.0 release. The 0.46.0 release was 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. +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. As a user of Qiskit, it's recommended that you first upgrade to this final minor version first, so you can see any deprecation warnings and adjust your Qiskit From 86f791fdc6b2e85b9a293a90aea1af83f8cafa2a Mon Sep 17 00:00:00 2001 From: Matthew Treinish Date: Mon, 20 Nov 2023 16:07:54 -0500 Subject: [PATCH 13/18] Remove qiskit-versioning from toc --- docs/start/_toc.json | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/start/_toc.json b/docs/start/_toc.json index a41cac70e7d..1634b60ab98 100644 --- a/docs/start/_toc.json +++ b/docs/start/_toc.json @@ -35,10 +35,6 @@ "url": "/start/configure-qiskit-local" } ] - }, - { - "title": "Qiskit Versioning", - "url": "/start/qiskit-versioning" } ] } From 44a8b7d62ac0991dcf95dd1b1ab047eccb42f9fc Mon Sep 17 00:00:00 2001 From: Matthew Treinish Date: Tue, 21 Nov 2023 10:59:09 -0500 Subject: [PATCH 14/18] Apply suggestions from code review Co-authored-by: Luciano Bello --- docs/start/install.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/start/install.mdx b/docs/start/install.mdx index 5b6f6d4941e..be1f7001bfb 100644 --- a/docs/start/install.mdx +++ b/docs/start/install.mdx @@ -201,7 +201,7 @@ dependency and the older version. Whenever a new major version is released, the recommended upgrade path is to first upgrade to use the most recent minor version on the previous major -version. Immediately preceding a new major version a final minor version will +version. Shortly before a new major version a final minor version will be published. This final minor version release `M.N+1.0` is equivalent to `M.N.0` but with warnings and deprecations for any API changes that are made on the new major version series. @@ -226,27 +226,27 @@ Pre-emptively capping the version less than the next major version is necessary to ensure you get a chance to see deprecation warnings before a major version release. The normal release schedule means the last minor version release which includes any final deprecation warnings will be released -at the same time as the next major version and `pip` will default to using +shortly before the next major version and `pip` will default to using the newest version available unless the version cap is set. ### Pre-releases For each minor and major version release Qiskit will publish pre-releases that are compatible with [PEP440](https://peps.python.org/pep-0440/). Typically -these are just release candidates of the form `1.2.0rc1`. The `rc` releases +these are just 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. If another PEP440 pre-release suffix (such as `a`, `b`, or `pre`) are published these do not have the same guarantees as an `rc` release, and are -just preview releases. The API likely will change between these pre-releases -and the final release with that version number. For example, `1.0.0pre1` has -a different final API from `1.0.0`. +just preview releases. 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 the packaging of a given release a post-release may be -issued to correct this. These will follow the form `1.2.1.1` where the fourth -integer is used to indicate it is the 1st post release of the `1.2.1` release. +issued to correct this. These will follow the form `X.Y.Z.1` where the fourth +integer is used to indicate it is the 1st 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 From af6d49d16c7be56582f66656a5089087085e6bdd Mon Sep 17 00:00:00 2001 From: Matthew Treinish Date: Wed, 22 Nov 2023 09:05:57 -0500 Subject: [PATCH 15/18] Apply suggestions from code review Co-authored-by: abbycross --- docs/start/install.mdx | 44 +++++++++++++++++++++--------------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/start/install.mdx b/docs/start/install.mdx index be1f7001bfb..db89e43d5cd 100644 --- a/docs/start/install.mdx +++ b/docs/start/install.mdx @@ -137,30 +137,30 @@ Additionally, Qiskit only supports CPython. Running with other Python interprete - Windows 32 bit for Python 3.10 or later -## Qiskit Versioning +## Qiskit versioning Qiskit version numbers follow [Semantic Versioning](https://semver.org/). -The version number is comprised of 3 primary components, the major, minor, and +The version number is comprised of three primary components: the major, minor, and patch versions. For a version number `X.Y.Z` where `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 will be periodically (currently every three months) published for the current major -version which add new features and bug fixes. For the most recent minor version, +version, which add new features and bug fixes. For the most recent minor version, there will also be new patch versions published as bugs are identified and fixed on that release series. A tentative release schedule is included below: ![](/images/start/install/release_schedule.png) -For an up-to-date release schedule you should refer to the Qiskit Github project's +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 6 months; only bug and security fixes will be accepted during this time and only patch releases will be published for this major version. A final -patch version will be published when support is dropped and that release will +patch version will be published when support is dropped, and that release will also document the end of support for that major version series. A longer support window is needed for the previous major version as this gives downstream consumers of Qiskit a chance to migrate not only their code but also their @@ -176,15 +176,15 @@ 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 a `_` prefix). However, there can be explicit exceptions made in the case of 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 +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 will be considered part of the public -API. Typically this only occurs in two cases, either an abstract interface +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 +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 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 @@ -197,16 +197,16 @@ 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 +### Upgrade strategy Whenever a new major version is released, the recommended upgrade path is to first upgrade to use the most recent minor version on the previous major -version. Shortly before a new major version a final minor version will +version. Shortly before a new major version, a final minor version will be published. This final minor version release `M.N+1.0` is equivalent to `M.N.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 +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 @@ -215,8 +215,8 @@ version releases. As a user of Qiskit, it's recommended that you first upgrade to this final minor version first, so you can see any deprecation warnings and adjust your Qiskit usage ahead of time before trying a potentially breaking release. The previous -major version will be supported for at least 6 months to give sufficient time -to upgrade. A typical pattern to deal with this is to pin the max version to +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 max version to avoid using the next major release series until you're sure of compatibility. For example, specifying in a requirements file `qiskit<2` when the current major Qiskit version is 1 will ensure that you're using a version of Qiskit @@ -233,24 +233,24 @@ the newest version available unless the version cap is set. For each minor and major version release Qiskit will publish pre-releases that are compatible with [PEP440](https://peps.python.org/pep-0440/). Typically -these are just release candidates of the form `X.Y.0rc1`. The `rc` releases +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. -If another PEP440 pre-release suffix (such as `a`, `b`, or `pre`) are -published these do not have the same guarantees as an `rc` release, and are -just preview releases. The API might change between these pre-releases +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 the packaging of a given release a post-release may be +If there are issues with the packaging of a given release, a post-release may be issued to correct this. These will follow the form `X.Y.Z.1` where the fourth -integer is used to indicate it is the 1st post release of the `X.Y.Z` release. +integer is used to indicate 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 +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 just fixed the packaging issue for the release. +0.25.2.1 only fixed the packaging issue for the release. ## Troubleshooting From f7ff76c4bbb8d4c17f6f1b8177282891834ae1c4 Mon Sep 17 00:00:00 2001 From: Matthew Treinish Date: Thu, 30 Nov 2023 17:59:10 -0500 Subject: [PATCH 16/18] Add details components --- docs/start/install.mdx | 221 +++++++++++++++++++++-------------------- 1 file changed, 113 insertions(+), 108 deletions(-) diff --git a/docs/start/install.mdx b/docs/start/install.mdx index db89e43d5cd..d33d7e68055 100644 --- a/docs/start/install.mdx +++ b/docs/start/install.mdx @@ -6,7 +6,7 @@ description: Install and set up Qiskit and Qiskit Runtime on various operating s # Install and set up Qiskit -Whether you will work locally or in a cloud environment, the first step for all users is to install Qiskit. For those wanting to run on a real backend, your next step is to choose one of two channels in order to access IBM Quantum systems: IBM Quantum Platform or IBM Cloud. +Whether you will work locally or in a cloud environment, the first step for all users is to install Qiskit. For those wanting to run on a real backend, your next step is to choose one of two channels in order to access IBM Quantum systems: IBM Quantum Platform or IBM Cloud. ## Install and set up Qiskit with the Qiskit Runtime Client @@ -63,7 +63,7 @@ Whether you will work locally or in a cloud environment, the first step for all 1. Install the following packages. - Periodically rerun these commands or check the [Qiskit release notes](../api/qiskit/release-notes) and the [Qiskit Runtime release notes](../api/qiskit-ibm-runtime/release-notes) so that you always have the latest versions. + Periodically rerun these commands or check the [Qiskit release notes](../api/qiskit/release-notes) and the [Qiskit Runtime release notes](../api/qiskit-ibm-runtime/release-notes) so that you always have the latest versions. ```shell @@ -138,119 +138,124 @@ Additionally, Qiskit only supports CPython. Running with other Python interprete ## Qiskit versioning - -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 a version number `X.Y.Z` where `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 will be -periodically (currently every three months) published for the current major -version, which add new features and bug fixes. For the most recent minor version, -there will also be new patch versions published as bugs are identified and fixed -on that release series. A tentative release schedule is included below: - -![](/images/start/install/release_schedule.png) - -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 6 months; only bug and security fixes will be accepted during this -time and only patch releases will be published for this major version. A final -patch version will be published when support is dropped, and that release will -also document the end of support for that major version series. A longer -support window is needed for the previous major version as this gives downstream -consumers of Qiskit a chance to migrate not only their code but also their -users. It's typically not recommended for a downstream library that -depends on Qiskit to bump its minimum Qiskit version to a new -major version release immediately because its user base also needs a chance -to migrate to the new API changes. Having an extended support window -for the previous major Qiskit version gives downstream projects time to fix -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 a `_` prefix). However, there can be explicit exceptions made in the case -of 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 will be 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. +
+ 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 a version number `X.Y.Z` where `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 will be + periodically (currently every three months) published for the current major + version, which add new features and bug fixes. For the most recent minor version, + there will also be new patch versions published as bugs are identified and fixed + on that release series. A tentative release schedule is included below: + + ![](/images/start/install/release_schedule.png) + + 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 6 months; only bug and security fixes will be accepted during this + time and only patch releases will be published for this major version. A final + patch version will be published when support is dropped, and that release will + also document the end of support for that major version series. A longer + support window is needed for the previous major version as this gives downstream + consumers of Qiskit a chance to migrate not only their code but also their + users. It's typically not recommended for a downstream library that + depends on Qiskit to bump its minimum Qiskit version to a new + major version release immediately because its user base also needs a chance + to migrate to the new API changes. Having an extended support window + for the previous major Qiskit version gives downstream projects time to fix + 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 a `_` prefix). However, there can be explicit exceptions made in the case + of 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 will be 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 - -Whenever a new major version is released, the recommended upgrade path -is to first upgrade to use 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 `M.N+1.0` is equivalent to -`M.N.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. - -As a user of Qiskit, it's recommended that you first upgrade to this final minor -version first, so you can see any deprecation warnings and adjust your Qiskit -usage ahead of time 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 max version to -avoid using the next major release series until you're sure of compatibility. -For example, specifying in a requirements file `qiskit<2` when the current -major Qiskit version is 1 will ensure that you're using a version of Qiskit -that won't have breaking API changes. - -Pre-emptively capping the version less than the next major version is necessary -to ensure you get a chance to see deprecation warnings before a -major version release. The normal release schedule means the last minor -version release which includes any final deprecation warnings will be released -shortly before the next major version and `pip` will default to using -the newest version available unless the version cap is set. +
+ Whenever a new major version is released, the recommended upgrade path + is to first upgrade to use 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 `M.N+1.0` is equivalent to + `M.N.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. + + As a user of Qiskit, it's recommended that you first upgrade to this final minor + version first, so you can see any deprecation warnings and adjust your Qiskit + usage ahead of time 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 max version to + avoid using the next major release series until you're sure of compatibility. + For example, specifying in a requirements file `qiskit<2` when the current + major Qiskit version is 1 will ensure that you're using a version of Qiskit + that won't have breaking API changes. + + Pre-emptively capping the version less than the next major version is necessary + to ensure you get a chance to see deprecation warnings before a + major version release. The normal release schedule means the last minor + version release which includes any final deprecation warnings will be released + shortly before the next major version and `pip` will default to using + the newest version available unless the version cap is set. +
### Pre-releases - -For each minor and major version release Qiskit will publish 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`. +
+ For each minor and major version release Qiskit will publish 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 the packaging of a given release, a post-release may be -issued to correct this. These will follow the form `X.Y.Z.1` where the fourth -integer is used to indicate 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. +
+ If there are issues with the packaging of a given release, a post-release may be + issued to correct this. These will follow the form `X.Y.Z.1` where the fourth + integer is used to indicate 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. +
## Troubleshooting From 7b153fa651108e6a32b9b96d5ba44d9debf5cacd Mon Sep 17 00:00:00 2001 From: Matthew Treinish Date: Thu, 30 Nov 2023 18:03:45 -0500 Subject: [PATCH 17/18] Apply suggestions from code review Co-authored-by: Kevin Hartman --- docs/start/install.mdx | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/docs/start/install.mdx b/docs/start/install.mdx index d33d7e68055..fe42da16c23 100644 --- a/docs/start/install.mdx +++ b/docs/start/install.mdx @@ -145,11 +145,16 @@ Additionally, Qiskit only supports CPython. Running with other Python interprete `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 will be - periodically (currently every three months) published for the current major - version, which add new features and bug fixes. For the most recent minor version, - there will also be new patch versions published as bugs are identified and fixed - on that release series. A tentative release schedule is included below: + 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 (i.e. + major version). We support at most two release series at a time, which occurs + only during the period of overlap following anew major version release, + described in more detail below. + + A tentative release schedule is included below: ![](/images/start/install/release_schedule.png) @@ -164,9 +169,9 @@ Additionally, Qiskit only supports CPython. Running with other Python interprete also document the end of support for that major version series. A longer support window is needed for the previous major version as this gives downstream consumers of Qiskit a chance to migrate not only their code but also their - users. It's typically not recommended for a downstream library that + users. We do not recommended for a downstream library that depends on Qiskit to bump its minimum Qiskit version to a new - major version release immediately because its user base also needs a chance + major version release immediately because its user base will also need a chance to migrate to the new API changes. Having an extended support window for the previous major Qiskit version gives downstream projects time to fix compatibility with the next major version. Downstream projects can provide From 797434ab9f521eb510209c5a18c8f16108482013 Mon Sep 17 00:00:00 2001 From: javabster Date: Fri, 1 Dec 2023 10:50:38 -0500 Subject: [PATCH 18/18] tidied up file --- docs/start/install.mdx | 122 ++++++++++++++++++++++------------------- 1 file changed, 67 insertions(+), 55 deletions(-) diff --git a/docs/start/install.mdx b/docs/start/install.mdx index fe42da16c23..e1a8f26cd1f 100644 --- a/docs/start/install.mdx +++ b/docs/start/install.mdx @@ -89,6 +89,57 @@ Whether you will work locally or in a cloud environment, the first step for all If you are planning to work locally and use simulators built into Qiskit, then your installation is done. If you want to run jobs on IBM Quantum systems, next [select an access channel](setup-channel) and finish your setup. +## Troubleshooting + +
+ + "No Module 'qiskit'" error with Jupyter Notebook + + If you used ``pip install qiskit`` and set up your virtual environment in + Anaconda, then you may get the ``No Module 'qiskit'`` error when you run a tutorial + in Jupyter Notebook. If you have not installed Qiskit or set up your + virtual environment, you can follow the [installation](#qiskit-install) steps. + + The error is caused when trying to import the Qiskit package in an + environment where Qiskit is not installed. If you launched Jupyter Notebook + from the Anaconda-Navigator, it is possible that Jupyter Notebook is running + in the base (root) environment, instead of in your virtual + environment. Choose a virtual environment in the Anaconda-Navigator from the + **Applications on** dropdown menu. In this menu, you can see + all of the virtual environments within Anaconda, and you can + select the environment where you have Qiskit installed to launch Jupyter + Notebook. +
+ +
+ + Compilation errors during installation + + Qiskit depends on a number of other open-source Python packages, which + are automatically installed when doing ``pip install qiskit``. Depending on + your system's platform and Python version, it is possible that a particular + package does not provide pre-built binaries for your system. You can refer + to [Operating system support](#operating-system-support) for a list of platforms supported by Qiskit, some + of which may need an extra compiler. In cases where there are + no precompiled binaries available, ``pip`` will attempt to compile the package + from source, which in turn might require some extra dependencies that need to + be installed manually. + + If the output of ``pip install qiskit`` contains similar lines to: + + ``` + Failed building wheel for SOME_PACKAGE + ... + build/temp.linux-x86_64-3.5/_openssl.c:498:30: fatal error + compilation terminated. + error: command 'x86_64-linux-gnu-gcc' failed with exit status 1 + ``` + + please check the documentation of the package that failed to install (in the + example code, ``SOME_PACKAGE``) for information on how to install the libraries + needed for compiling from source. +
+ ## Operating system support @@ -138,7 +189,6 @@ Additionally, Qiskit only supports CPython. Running with other Python interprete ## Qiskit versioning -
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 a version number `X.Y.Z` where `X` is the major version, @@ -154,6 +204,11 @@ Additionally, Qiskit only supports CPython. Running with other Python interprete only during the period of overlap following anew major version release, described in more detail below. + +
+ + Release schedule + A tentative release schedule is included below: ![](/images/start/install/release_schedule.png) @@ -203,8 +258,11 @@ Additionally, Qiskit only supports CPython. Running with other Python interprete dependency and the older version.
-### Upgrade strategy +
+ + Upgrade strategy + Whenever a new major version is released, the recommended upgrade path is to first upgrade to use the most recent minor version on the previous major version. Shortly before a new major version, a final minor version will @@ -236,8 +294,11 @@ Additionally, Qiskit only supports CPython. Running with other Python interprete the newest version available unless the version cap is set.
-### Pre-releases +
+ + Pre-releases + For each minor and major version release Qiskit will publish 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 @@ -250,9 +311,11 @@ Additionally, Qiskit only supports CPython. Running with other Python interprete a different final API than `1.0.0`.
-### Post-releases
+ + Post-releases + If there are issues with the packaging of a given release, a post-release may be issued to correct this. These will follow the form `X.Y.Z.1` where the fourth integer is used to indicate it is the first post-release of the `X.Y.Z` release. @@ -262,57 +325,6 @@ Additionally, Qiskit only supports CPython. Running with other Python interprete 0.25.2.1 only fixed the packaging issue for the release.
-## Troubleshooting - -
- - "No Module 'qiskit'" error with Jupyter Notebook - - If you used ``pip install qiskit`` and set up your virtual environment in - Anaconda, then you may get the ``No Module 'qiskit'`` error when you run a tutorial - in Jupyter Notebook. If you have not installed Qiskit or set up your - virtual environment, you can follow the [installation](#qiskit-install) steps. - - The error is caused when trying to import the Qiskit package in an - environment where Qiskit is not installed. If you launched Jupyter Notebook - from the Anaconda-Navigator, it is possible that Jupyter Notebook is running - in the base (root) environment, instead of in your virtual - environment. Choose a virtual environment in the Anaconda-Navigator from the - **Applications on** dropdown menu. In this menu, you can see - all of the virtual environments within Anaconda, and you can - select the environment where you have Qiskit installed to launch Jupyter - Notebook. -
- -
- - Compilation errors during installation - - Qiskit depends on a number of other open-source Python packages, which - are automatically installed when doing ``pip install qiskit``. Depending on - your system's platform and Python version, it is possible that a particular - package does not provide pre-built binaries for your system. You can refer - to [Operating system support](#operating-system-support) for a list of platforms supported by Qiskit, some - of which may need an extra compiler. In cases where there are - no precompiled binaries available, ``pip`` will attempt to compile the package - from source, which in turn might require some extra dependencies that need to - be installed manually. - - If the output of ``pip install qiskit`` contains similar lines to: - - ``` - Failed building wheel for SOME_PACKAGE - ... - build/temp.linux-x86_64-3.5/_openssl.c:498:30: fatal error - compilation terminated. - error: command 'x86_64-linux-gnu-gcc' failed with exit status 1 - ``` - - please check the documentation of the package that failed to install (in the - example code, ``SOME_PACKAGE``) for information on how to install the libraries - needed for compiling from source. -
- ## Next steps