Skip to content

Commit

Permalink
Add anchors to show/hide sections in install page (#589)
Browse files Browse the repository at this point in the history 
EDIT: Adding custom anchor tags to the show/hide sections in the "Qiskit
versioning" section.

Once this is merged, direct links to the show-hide sections will be:

https://docs.quantum.ibm.com/start/install#release-schedule
https://docs.quantum.ibm.com/start/install#upgrade-strategy
https://docs.quantum.ibm.com/start/install#pre-releases
https://docs.quantum.ibm.com/start/install#post-releases


---------------------------
(Original proposal below, for historical purposes; we are no longer
separating out the versioning section to a new page.)
In discussions with @mtreinish, the proposal is to separate out the
versioning section (currently at the end of the start/install page) into
a new page, for the following reasons:

- it really isn't directly install-related
- it allows us to remove the show/hide features for that content, which
makes it easier to link to and find

We may also want to remove the show/hide features for the OS support
tiers, but leave them in the current install page, since they are
install-related.

Topics to discuss:

- [ ] What to put in Next steps section? Currently using the same as
what is on the Install pg as a placeholder.
- [ ] Title at the moment is just Qiskit versioning (since that's the
only thing in the new page); are we good with this?
- [ ] I put the new page after the "Advanced setup" section in the toc.
Should it be elsewhere?

cc: @mtreinish @Eric-Arellano

---------

Co-authored-by: Rebecca Dimock <66339736+beckykd@users.noreply.github.com>
Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
  • Loading branch information
@abbycross @beckykd @Eric-Arellano
3 people authored Jan 19, 2024
1 parent 25d99dc commit 7738c59
Showing 1 changed file with 102 additions and 104 deletions.
206 changes: 102 additions & 104 deletions docs/start/install.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ description: Install and set up Qiskit and Qiskit Runtime on various operating s
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 system, your next step is to choose one of two channels in order to access IBM Quantum systems: IBM Quantum Platform or IBM Cloud.

<span id="local"></span>
## Install and set up Qiskit with the Qiskit Runtime Client
## Install and set up Qiskit with the Qiskit Runtime client

1. Install Python. Check the requirements in the [setup.py](https://github.com/Qiskit/qiskit/blob/main/setup.py) file to determine which Python versions are supported. For download instructions, see the [Python Beginners Guide.](https://wiki.python.org/moin/BeginnersGuide/Download)

Expand Down Expand Up @@ -187,20 +187,21 @@ Additionally, Qiskit only supports CPython. Running with other Python interprete
</details>

## 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 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.

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.


<details>
Expand All @@ -212,115 +213,112 @@ Additionally, Qiskit only supports CPython. Running with other Python interprete
![](/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. 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 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
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.
[milestones list](https://github.com/Qiskit/qiskit/milestones), which always contains 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.
</details>


<details>
<summary>
Upgrade strategy
</summary>
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.
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.
</details>


<details>
<summary>
Pre-releases
</summary>
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 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`.
</details>


<details>
<summary>
Post-releases
</summary>
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 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.
</details>

## Next steps
Expand All @@ -330,4 +328,4 @@ Additionally, Qiskit only supports CPython. Running with other Python interprete
- [Configure Qiskit locally.](configure-qiskit-local)
- Follow the steps in [Hello world](hello-world) to write and run a quantum program.
- Try one of the [workflow example tutorials.](https://learning.quantum.ibm.com/catalog/tutorials?category=workflow-example)
</Admonition>
</Admonition>

0 comments on commit 7738c59

Please sign in to comment.