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

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