Document Qiskit versioning and stability policy

cSpell.json

@@ -249,7 +249,8 @@
     "mathrm",
     "exponentiated",
     "simulable",
-    "resynthesizes"
+    "resynthesizes",
+    "sdist"
   ],
   "ignoreRegExpList": [
     // Markdown links

docs/start/install.mdx

@@ -137,6 +137,121 @@ Additionally, Qiskit only supports CPython. Running with other Python interprete
   - Windows 32 bit for Python 3.10 or later
 </details>
 
+## 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 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 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
+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 `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
+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 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
+0.25.2.1 just fixed the packaging issue for the release.
+
 ## Troubleshooting
 
 <details>
@@ -188,11 +303,10 @@ Additionally, Qiskit only supports CPython. Running with other Python interprete
   needed for compiling from source.
 </details>
 
-
 ## Next steps
 
 <Admonition type="tip" title="Recommendations">
   -  [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.
-</Admonition>
+</Admonition>