diff --git a/docs/deprecation_policy.rst b/docs/deprecation_policy.rst index 997aa8172fa8..558744a8a9a7 100644 --- a/docs/deprecation_policy.rst +++ b/docs/deprecation_policy.rst @@ -1,3 +1,105 @@ +############################# +Versioning and Support Policy +############################# + +Qiskit version numbers follow `Semantic Versioning `__. +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. + +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). 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. + + + +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. + +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. + ################## Deprecation Policy ################## @@ -21,17 +123,20 @@ underscore (``_``). The guiding principles are: -- we must not remove or change code without active warnings for least three - months or two complete version cycles; +- we must not remove or change code without active warnings on a supported + release series for at least three months and removals can only occur on + major version releases; - there must always be a way to achieve valid goals that does not issue any warnings; - never assume that a function that isn't explicitly internal isn't in use; -- all deprecations, changes and removals are considered API changes, and can - only occur in minor releases not patch releases, per the - :ref:`stable branch policy `. +- all deprecations can only occur in minor version releases not patch version + releases, per the :ref:`stable branch policy `. + +- API changes and removals are considered breaking changes, and can only + occur in major version releases. .. _removing-features: diff --git a/docs/maintainers_guide.rst b/docs/maintainers_guide.rst index ed2a6b508cdf..112ed5419f87 100644 --- a/docs/maintainers_guide.rst +++ b/docs/maintainers_guide.rst @@ -32,14 +32,27 @@ change: a change already merged onto ``main``, unless the change simply does not make sense on ``main``. +At any given time Qiskit has up to two supported stable branches, one for the +previous minor version release series and the other for the final minor +release series on the previous major release. For example, if the ``main`` +branch is developing the 1.2.0 release, then the ``stable/1.1`` branch and +potentially the ``stable/0.46`` branches are supported. Backporting ----------- When a PR tagged with ``stable backport potential`` is merged, or when a merged PR is given that tag, the `Mergify bot `__ will -open a PR to the current stable branch. You can review and merge this PR -like normal. +open a PR to the most recent supported stable branch. You can review and merge +this PR like normal. If you're backporting from main to a different stable +branch you can leave a comment of the form ``@Mergifyio backport branch`` on a +merged PR to manually have the Mergify bot backport the PR to the specified +branch. + +If the version of the code has diverged or no longer exists on the stable +branch it is acceptable to directly propose a change to the stable branch. But +it is expected to document the reasons why in the commit message, as the +typical procedure is to merge on ``main`` first. Documentation Structure