Document versioning and deprecation policy for major versions #11205

mtreinish · 2023-11-06T19:35:33Z

Summary

This commit document expands the versioning, deprecation, and stability polices to document the policy around major versions. The previous policies were all written without any consideration for major versioning. This outlines the minimum support windows for major versions and how deprecations and breaking changes will work with regards to versioning. It also explicitly documents that Qiskit is using semantic versioning. This is a actually a change from historical releases prior to Qiskit 0.44.0 where we explicitly did not follow semantic versioning as the version number was based on the qiskit elements.

This is an expanded document outlining the procedures decided on in the discussion around Qiskit/RFCs#34.

Details and comments

This commit document expands the versioning, deprecation, and stability polices to document the policy around major versions. The previous policies were all written without any consideration for major versioning. This outlines the minimum support windows for major versions and how deprecations and breaking changes will work with regards to versioning. It also explicitly documents that Qiskit is using semantic versioning. This is a actually a change from historical releases prior to Qiskit 0.44.0 where we explicitly did not follow semantic versioning as the version number was based on the qiskit elements. This is an expanded document outlining the procedures decided on in the discussion around Qiskit/RFCs#34.

qiskit-bot · 2023-11-06T19:35:38Z

One or more of the the following people are requested to review this:

@Eric-Arellano
@javabster
@Qiskit/terra-core

coveralls · 2023-11-06T19:58:39Z

Pull Request Test Coverage Report for Build 6882844407

Warning: This coverage report may be inaccurate.

We've detected an issue with your CI configuration that might affect the accuracy of this pull request's coverage report.
To ensure accuracy in future PRs, please see these guidelines.
A quick fix for this PR: rebase it; your next report should be accurate.

0 of 0 changed or added relevant lines in 0 files are covered.
493 unchanged lines in 39 files lost coverage.
Overall coverage decreased (-1.0%) to 85.905%

Files with Coverage Reduction	New Missed Lines	%
qiskit/circuit/library/blueprintcircuit.py	1	92.24%
qiskit/circuit/library/evolved_operator_ansatz.py	1	85.12%
qiskit/opflow/state_fns/operator_state_fn.py	1	80.22%
qiskit/opflow/state_fns/state_fn.py	1	81.88%
qiskit/primitives/backend_sampler.py	1	98.84%
qiskit/primitives/utils.py	1	87.8%
qiskit/providers/backend.py	1	81.76%
qiskit/providers/basicaer/basicaerprovider.py	1	94.34%
qiskit/quantum_info/operators/symplectic/pauli_list.py	1	83.16%
qiskit/quantum_info/operators/symplectic/pauli.py	1	83.47%

Totals
Change from base Build 6827950580:	-1.0%
Covered Lines:	65944
Relevant Lines:	76764

💛 - Coveralls

docs/deprecation_policy.rst

Co-authored-by: Elena Peña Tapia <57907331+ElePT@users.noreply.github.com>

docs/deprecation_policy.rst

wshanks · 2023-11-07T16:31:13Z

docs/deprecation_policy.rst

- 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


The three month window is a little unclear to me. Regarding removals, couldn't it just be said that removals should only be done in the next major release, without regard to a window? And should changes be allowed with a three month warning? Or should they just be kicked to the next major release as well?

I'll just remove this. I left it in because in the semantic versioning model everything will be deprecated for at least 6 months because of the extended support. I was thinking we still wanted to have a minimum deprecation window duration, but in the model there isn't really path for it to be < 6 months so this isn't needed anymore.

wshanks · 2023-11-07T16:35:46Z

docs/deprecation_policy.rst

+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


I like the use of "documented" here, but I am not sure it agrees with the text in the "Deprecation Policy" section below:

Beware that users will often be using functions, classes and methods that we, the Qiskit developers, may consider internal or not widely used. Do not make assumptions that "this is buried, so nobody will be using it"; if it is public, it is subject to the policy.

and

never assume that a function that isn't explicitly internal isn't in use

If something is not documented but does not start with a _, can it be removed? Should "public" in the quoted section above be "publicly documented?"

I should update the deprecation policy section below I think. There was an ambiguity in expectations for some people around public functions that are in weird modules. For example something like qiskit.transpiler.passes.layout.vf2_utils.score_layout() which is not documented in the published api docs and I wrote to be internal but under the deprecation policy wording would be viewed as public. My thinking by explicitly saying documented is to tighten the potential surface and make it clear what's expected to be treated as public.

I'll reword this a bit to be more clear, because I think there are some cases where private methods are part of a stable interface. The best example I can think of are things like interface definitions that have abstract private methods that need to be defined.

Yeah, there are a couple of cases where _* names are public:

Advanced-usage low-level methods we commit to stability in, for downstream code to use if they guarantee to uphold the class/safety invariants themselves. The archetypal example of this is QuantumCircuit._append, which is meant to be documented, but I think Sphinx might be overlooking it at the moment.

Abstract methods in base classes that are explicitly meant for subclasses to override. These are often prefixed with an underscore to show that users aren't meant to call them directly, but the interface classes call them. Things like SingletonInstruction._singleton_lookup_key fall into this category.

wshanks · 2023-11-07T16:44:16Z

docs/deprecation_policy.rst

+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


What does it mean that it documents the end of the release? Its release notes will say that there is no more support? If there are no bug fixes at that time, will it just be identical to the previous patch release other than the release notes?

It's just the release notes. I was thinking we'd just put in the prelude something like: "0.46.5 is the final release of the 0.x release series of Qiskit. There will be no future releases of 0.x and you should migrate to using a 1.x release."

wshanks · 2023-11-07T16:54:42Z

docs/deprecation_policy.rst

+version. Immediately preceding a new major version a final minor version will
+be published. This final minor version release ``0.N+1.0`` is equivalent to
+``0.N.0`` but with warnings and deprecations for any API changes that are
+made on the new major version series.


I think the "deprecation policy" section below might need to be updated to account for this final minor version and the new use of major versions. It talks about removing features only after providing an alternate path for one minor, warnings for one minor, and then removal at least two minors after the warnings. I think the idea is that with this final minor Qiskit can issue warnings for things removed in the next major even though they are released almost simultaneously because the final minor has an extended support window? I am not sure about the requirement to provide an alternate path before removal under the new semantic versioning model. If removing a feature in Qiskit 2.0, does anything have to happen in Qiskit 1 besides a deprecation in the final minor version?

I was thinking that ideally we'd still be adding the warnings and the alternative features in minor version releases ahead of the the 1->2 migration. In those cases we'd still want to follow that guidance. But in general yeah you're right there isn't a hard requirement for that, especially at the 1->2 migration point. I'll update the deprecation section to take this into account.

Co-authored-by: Will Shanks <wshaos@posteo.net>

wshanks · 2023-11-07T17:15:54Z

docs/maintainers_guide.rst

-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


Would it be worth adding a previous stable backport potential label to .mergify.yml?

Oh, yeah this is a good idea we can totally do this. I'll update the docs to include this.

If we're going this route, I wouldn't mind doing it as explicit labels (backport to 0.45, backport to 1.1, etc) - it's more work to manage Mergify since we can't easily make it dynamic on the label, but I already sometimes forget what "stable backport potential" means when we're in an rc period.

docs/deprecation_policy.rst

Co-authored-by: Will Shanks <wshaos@posteo.net>

nkanazawa1989

Thanks Matthew. Overall what this document describes looks reasonable and gives useful guideline for community developers.

My main concern is the pattern to develop a new feature. Since Qiskit doesn't use feature branches, this document implicitly suggests developers to use versioned classes to buffer the API change. This might be manageable if the package exposes only several public classes. However if every class gains its version, the class dependency would become too complicated to deal with, e.g. QuantumCircuitV2 supports GateV4 inherit from InstructionV3, and ScheduleBlockV5 for calibration. Then we would want to alias a class at package level. For example import QuantumCircuitV2 as QuantumCircuit which is breaking API change to users. It doesn't need to reside in this document, but we may want some reasonable pattern for new feature development before accepting this release policy. Probably we can make the most use of RFC?

nkanazawa1989 · 2023-11-14T02:18:25Z

docs/deprecation_policy.rst

+
+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


Maybe 0.45.x since 46 is built upon the latest patch release.

Another question would be; as a developer in which version can we add deprecation warnings if we want to upgrade API in next major release? Do we need to wait for N.M+1.0 and open a separate PR to that branch for deprecation? Seems like we need to keep it in our todo list for a year at most.

You can add deprecations in any minor/major version, the exception being 1.0, because we're trying to make 1.0 deprecation warning free. For example I'm already planning deprecations for 1.1: #11212

docs/deprecation_policy.rst

jakelishman · 2023-11-14T13:24:41Z

docs/deprecation_policy.rst

+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


Yeah, there are a couple of cases where _* names are public:

Advanced-usage low-level methods we commit to stability in, for downstream code to use if they guarantee to uphold the class/safety invariants themselves. The archetypal example of this is QuantumCircuit._append, which is meant to be documented, but I think Sphinx might be overlooking it at the moment.

Abstract methods in base classes that are explicitly meant for subclasses to override. These are often prefixed with an underscore to show that users aren't meant to call them directly, but the interface classes call them. Things like SingletonInstruction._singleton_lookup_key fall into this category.

jakelishman · 2023-11-14T13:30:02Z

docs/maintainers_guide.rst

-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


If we're going this route, I wouldn't mind doing it as explicit labels (backport to 0.45, backport to 1.1, etc) - it's more work to manage Mergify since we can't easily make it dynamic on the label, but I already sometimes forget what "stable backport potential" means when we're in an rc period.

Co-authored-by: Jake Lishman <jake@binhbar.com>

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

mtreinish · 2023-11-16T19:05:26Z

I'm going to close this PR, because of the change in the documentation strategy I've reopened this here: Qiskit/documentation#366 which is where it'll get documented from. There are still going to be the changes needed to the developer documentation around deprecations. Those will live in markdown files that aren't included in the doc builds by default here: #11218. I'll rework that piece of this PR into a new PR after #11218 merges

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). --------- Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> Co-authored-by: Luciano Bello <bel@zurich.ibm.com> Co-authored-by: abbycross <across@us.ibm.com> Co-authored-by: Kevin Hartman <kevin@hart.mn> Co-authored-by: javabster <abby.s.mitchell@gmail.com> Co-authored-by: Abby Mitchell <23662430+javabster@users.noreply.github.com>

mtreinish added documentation Something is not clear or an error documentation priority: high Changelog: None Do not include in changelog labels Nov 6, 2023

mtreinish added this to the 1.0.0pre1 milestone Nov 6, 2023

mtreinish requested a review from a team as a code owner November 6, 2023 19:35

mtreinish requested a review from wshanks November 6, 2023 19:35

mtreinish mentioned this pull request Nov 6, 2023

Remove deprecated legacy pulse builder commands #11191

Merged

Fix heading consistency

c8bed1f

ElePT reviewed Nov 7, 2023

View reviewed changes

docs/deprecation_policy.rst Outdated Show resolved Hide resolved

mtreinish and others added 2 commits November 7, 2023 05:56

Update docs/deprecation_policy.rst

c34d724

Co-authored-by: Elena Peña Tapia <57907331+ElePT@users.noreply.github.com>

Add paragraph on public API surface

7fc4dfc

wshanks reviewed Nov 7, 2023

View reviewed changes

Apply suggestions from code review

434c788

Co-authored-by: Will Shanks <wshaos@posteo.net>

wshanks reviewed Nov 7, 2023

View reviewed changes

docs/deprecation_policy.rst Outdated Show resolved Hide resolved

mtreinish and others added 3 commits November 7, 2023 16:28

Update docs/deprecation_policy.rst

067247c

Co-authored-by: Will Shanks <wshaos@posteo.net>

Update text

c46454d

Merge remote-tracking branch 'origin/main' into 1.0-policies

72012b9

nkanazawa1989 reviewed Nov 14, 2023

View reviewed changes

jakelishman reviewed Nov 14, 2023

View reviewed changes

jakelishman mentioned this pull request Nov 14, 2023

Convert deprecation policy and maintainer guide to markdown #11218

Merged

Update docs/deprecation_policy.rst

b38ce5b

Co-authored-by: Jake Lishman <jake@binhbar.com>

mtreinish mentioned this pull request Nov 16, 2023

Document Qiskit versioning and stability policy Qiskit/documentation#366

Merged

mtreinish closed this Nov 16, 2023

jakelishman mentioned this pull request Jan 8, 2024

Deprecate qiskit.Aer and qiskit.providers.aer #11439

Merged

jakelishman mentioned this pull request Feb 12, 2024

Update deprecation policy document for Qiskit 1.0 #11775

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document versioning and deprecation policy for major versions #11205

Document versioning and deprecation policy for major versions #11205

mtreinish commented Nov 6, 2023

qiskit-bot commented Nov 6, 2023

coveralls commented Nov 6, 2023 •

edited

Loading

wshanks Nov 7, 2023

mtreinish Nov 7, 2023

wshanks Nov 7, 2023

mtreinish Nov 7, 2023

jakelishman Nov 14, 2023

wshanks Nov 7, 2023

mtreinish Nov 7, 2023

wshanks Nov 7, 2023

mtreinish Nov 7, 2023 •

edited

Loading

wshanks Nov 7, 2023

mtreinish Nov 9, 2023

jakelishman Nov 14, 2023

nkanazawa1989 left a comment •

edited

Loading

nkanazawa1989 Nov 14, 2023

mtreinish Nov 16, 2023

jakelishman Nov 14, 2023

jakelishman Nov 14, 2023

mtreinish commented Nov 16, 2023

Document versioning and deprecation policy for major versions #11205

Document versioning and deprecation policy for major versions #11205

Conversation

mtreinish commented Nov 6, 2023

Summary

Details and comments

qiskit-bot commented Nov 6, 2023

coveralls commented Nov 6, 2023 • edited Loading

Pull Request Test Coverage Report for Build 6882844407

Warning: This coverage report may be inaccurate.

💛 - Coveralls

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mtreinish Nov 7, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nkanazawa1989 left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mtreinish commented Nov 16, 2023

coveralls commented Nov 6, 2023 •

edited

Loading

mtreinish Nov 7, 2023 •

edited

Loading

nkanazawa1989 left a comment •

edited

Loading