Document Qiskit versioning and stability policy

docs/start/qiskit-versioning.mdx

@@ -0,0 +1,126 @@
+---
+title: Qiskit Versioning and Support Policy
+description: The versioning and support policy for Qiskit.
+
+---
+<span id="qiskit-version"></span>
+# 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.
+
+<span id="upgrade"></span>
+## 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.
+
+<span id="pre-releases"></span>
+## 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`.
+
+<span id="post-releases"></span>
+## 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.