Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Qiskit release cycle and versioning #34

Merged
merged 28 commits into from
Mar 5, 2024
Merged

Qiskit release cycle and versioning #34

Changes from 7 commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
472b58a
initial draft
1ucian0 Apr 26, 2023
1bcf87b
gantt
1ucian0 Apr 26, 2023
e5f3409
title
1ucian0 Apr 26, 2023
e4eeb2c
suggestion
1ucian0 Apr 26, 2023
b625cd6
suggestion
1ucian0 Apr 27, 2023
87bbcee
summary, motivation, and user benefits
1ucian0 May 13, 2023
299654b
adding deprecation comments from https://github.com/Qiskit/RFCs/pull/…
1ucian0 May 19, 2023
566e9b8
title
1ucian0 May 21, 2023
11b97b4
current branch structure
1ucian0 May 23, 2023
24145f7
X.4.*
1ucian0 May 23, 2023
5e56c51
should-haves of the suggested solution
1ucian0 May 23, 2023
b9fdb99
suggested gitGraph
1ucian0 Jun 4, 2023
e401ee3
explanation
1ucian0 Jun 4, 2023
49ad562
stable
1ucian0 Jun 5, 2023
4233c9a
detailed
1ucian0 Nov 22, 2023
5915ae6
definition of public api
1ucian0 Nov 22, 2023
8302fa7
branching
1ucian0 Nov 28, 2023
23dc1c2
upgrade path
1ucian0 Dec 11, 2023
647325c
branching model
1ucian0 Dec 11, 2023
a8a6fcc
Update ####-release_cycle.md
1ucian0 Mar 1, 2024
c7a5fb8
Update ####-release_cycle.md
1ucian0 Mar 1, 2024
ee82646
Apply suggestions from code review
1ucian0 Mar 1, 2024
3ec912b
final minor release
1ucian0 Mar 3, 2024
d117b2c
QPY
1ucian0 Mar 3, 2024
ddfc671
mermeid fix
1ucian0 Mar 3, 2024
f54ad29
mermeid gantt fix
1ucian0 Mar 3, 2024
f61a233
Feature, Deprecation, and Removal Proposal Deadline
1ucian0 Mar 3, 2024
a8d0971
Update ####-release_cycle.md
1ucian0 Mar 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
138 changes: 138 additions & 0 deletions ####-release_cycle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,138 @@
# Qiskit release cycle and versioning

| **Status** | **Proposed/Accepted/Deprecated** |
|:------------------|:---------------------------------------------|
| **RFC #** | #### |
| **Authors** | [Luciano Bello](https://github.com/1ucian0/) |
| **Submitted** | 2023-04-26 |
| **Updated** | YYYY-MM-DD |

## Summary

Balancing stable backward compatibility with the rapid pace of technology is a crucial consideration for Qiskit. This RFC is a public discussion that aims to find a harmonious solution that offers users a clear and transparent support contract while minimizing the burden on developers and users. Ideally, we are in the search for an approach that also maximizes flexibility to accommodate new hardware and services, which often necessitate the development of new features.


## Motivation

> - Why are we doing this?
> - What will this enable?
> - What will be the outcome?
> - Who will benefit?

Qiskit is known for its dynamic nature and frequent deprecation of features. However, it [deprecation policy](https://qiskit.org/documentation/deprecation_policy.html) places a strong emphasis on stability and guarantees a relatively lengthy transition period (usually longer than six months from the notification point on) when removing a feature. For the last years, Qiskit also introduced planned releases for mitigating the impact of coming changes, as well as pre-releases.

However, there is a demand for a more transparent release cycle with longer periods of backwards compatibility support. In order to get ready for a "beyond Qiskit 0.x", a discussion on how that cycle would like is key to understand the trade-offs among:

* developer effort: Supporting several stable versions requires significant development resources. At the same time, rolling releases tend to create technical debt and few chance of rebuild from scratch particular modules.
1ucian0 marked this conversation as resolved.
Show resolved Hide resolved
* user support: users tend to demand longer support periods to avoid regular updates on their code and software.
1ucian0 marked this conversation as resolved.
Show resolved Hide resolved
* new feature support for coming technology: the quantum computing field and hardware is in constant change and scaling to it many time requires big changes in Qiskit, not always compatible with previous approaches.
1ucian0 marked this conversation as resolved.
Show resolved Hide resolved

The outcome of the RFC is an agreement for release cycle and a versioning schema that would provide users with the tools for planning and stability while reduce the impact in the development workflow.

**out-of-scope**:
The starting date for the implementation of this RFC is, in principle, outside the scope of this document.

## User Benefit

The RFC aims to benefit users and Qiskit ecosystem developers, because they will have guaranties that their software will run for a defined period of time and they could plan the transition period.

## Design Proposal
> This is the focus of the document. Explain the proposal from the perspective of
> educating another user on the proposed features.
>
> This generally means:
>
> - Introducing new concepts and nomenclature
> - Using examples to introduce new features
> - Implementation and Migration path with associated concerns
> - Communication of features and changes to users
>
> Focus on giving an overview of impact of the proposed changes to the target
> audience.
>
> Factors to consider:
>
> - Performance
> - Dependencies
> - Maintenance
> - Compatibility

Currently

```mermaid
gantt
dateFormat YYYY-MM-DD
tickInterval 3month
todayMarker off
axisFormat %b-%Y
0.17 :r017, 2021-04-01, 2021-07-12
0.18 :r018, after r017, 2021-12-06
0.19 :r019, after r018, 2022-03-31
0.20 :r020, after r019, 2022-06-30
0.21rc :r021rc, 2022-06-23, 2022-06-30
0.21 :r021, after r020, 2022-10-13
0.22rc :r022rc, 2022-10-07, 2022-10-13
0.22 :r022, after r021, 2023-01-26
0.23rc :r023rc, 2023-01-16, 2023-01-26
0.23 :r024, after r022, 2023-05-04
0.24rc :r024rc, 2023-04-20, 2023-05-04
0.24 :milestone, 2023-05-04
```

Suggest
```mermaid
gantt
dateFormat YYYY-MM-DD
tickInterval 3month
todayMarker off
axisFormat %b
section X.*
X.0 :rX0Y0, 2024-01-31, 91d
X.1 :rX0Y1, after rX0Y0, 91d
X.2 :rX0Y2, after rX0Y1, 91d
X.3 :rX0Y3, after rX0Y2, 91d
X.3.* :done, X0Y3s, after rX0Y3, 183d
section X+1.*
X+1.0 :rX1Y0, after rX0Y3, 91d
X+1.1 :rX1Y1, after rX1Y0, 91d
X+1.2 :rX1Y2, after rX1Y1, 91d
X+1.3 :rX1Y3, after rX1Y2, 91d
X+1.3.* :done, rX1Y3s, after rX1Y3, 183d
section X+2.*
X+2.0 :rX2Y0, after rX1Y3, 91d
X+2.1 :rX2Y1, after rX2Y0, 91d
X+2.2 :rX2Y2, after rX2Y1, 91d
X+2.3 :rX2Y3, after rX2Y2, 91d
X+2.3.* :done, rX2Y3s, after rX2Y3, 183d
```

## Detailed Design

> Technical reference level design. Elaborate on details such as:
1ucian0 marked this conversation as resolved.
Show resolved Hide resolved
>
> - Implementation procedure
> - If spans multiple projects cover these parts individually
> - Interaction with other features
> - Dissecting corner cases
> - Reference definition, eg., formal definitions.


### Deprecations

* deprecation warnings can only occur 1+ minor releases after the replacement functionality is added
* deprecation warnings must be emitted for a complete major version" (i.e. 1+ year)
Copy link
Member Author

@1ucian0 1ucian0 May 19, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added from #34 (comment) @jakelishman

I would like to offer an alternative as this sounds like a lot of time to me. Introducing a deprecation warning in X.Y and not being able to remove it until X+2.0 is a huge time period of dangling code. If we keep X.3 support for 6 extra month, that should be enough to remove it in X+1.0.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see the trouble with this approach is that it assumes that every user will upgrade through every minor version, so will see deprecations introduced in minor releases. To me, introducing major versions means that we expect that the required upgrade path is only at the granularity of "through each major version", and so my form is what guarantees that a user will see every deprecation warning.

Copy link
Member

@jakelishman jakelishman May 19, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For example, currently our upgrade strategy is that you can't expect to go from Terra 0.22 to 0.24 without something breaking without warning - you must go via 0.23 to ensure you've seen all warnings and had the opportunity to smoothly upgrade, and the deprecation policy also includes elements that require that there's a smooth no-error path you can take for a downstream library to support two consecutive minors, which is necessary for library authors to avoid needing precise latest-version-only pins.

I would foresee that if we add major versioning, the story ought to be "you must upgrade through each major, but you needn't install each minor", and then to keep the same spirit as our current deprecation policy, you need the deprecation warnings through an entire major release cycle.

I should be clear that what I said above is stricter than the official semantic-versioning story (which only requires a single minor release for a deprecation).

Copy link
Member

@garrison garrison May 22, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it assumes that every user will upgrade through every minor version, so will see deprecations introduced in minor releases.

Actually, the necessary assumption is weaker: before upgrading to a new major version, the user would only need to use the final minor version of the previous release, because there, all deprecation warnings necessary for upgrading will be visible and can be fixed.

Julia is an example that illustrates both the benefits and drawbacks of this approach. Julia 0.7.0 and 1.0.0 were released within ~48 hours of each other. The only difference between them is that 0.7.0 contained compatibility (and deprecation warnings) for code that worked under 0.6, while 1.0 removed all such support. If there is ever a Julia 2.0, I expect the same thing to happen: users will be expected to use the "final" 1.X release and fix all deprecation warnings before trying the code under Julia 2.0.

The downside to this approach was that, in practice, people not intimately familiar with the release plan upgraded directly from 0.6.x to 1.0, and were met with a poor user experience: tons of code that worked on the previous release simply failed. If the goal is to get users to use a certain release before upgrading, it really does need to be emphasized in all the obvious locations, and then some.

Copy link
Member Author

@1ucian0 1ucian0 May 23, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

people not intimately familiar with the release plan upgraded directly from 0.6.x to 1.0, and were met with a poor user experience: tons of code that worked on the previous release simply failed.

I see this as expected, as a major upgrade.

I see the trouble with this approach is that it assumes that every user will upgrade through every minor version

Indeed. This is an assumption that needs to be explicit. However, it is not more obscure than the current one.
Downstream library should depend on the fairly standard ~=X.Y or ==X.*. With the extended period for X.4.* receiving critical bug fix support and not introducing new deprecations, pinning the previous major is always an option and gives a good period of time to migrate.

Copy link
Member

@jakelishman jakelishman May 23, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My issue is that adding major versions into the mix does change the "obscurity" of the policy. I expect that code I write for one version of a library with no warnings will work in the next version of that library (now maybe with warnings), at whatever granularity that library does it major releases. Once we have majors, I see them as defining the required-upgrade granularity, as opposed to our current system where minors are that top level. That's not a requirement of semantic versioning as a spec, but that's because that spec is only for associating the scope of changes with the version number, not for any of the development/upgrade strategies that go with it.

Requiring that the 2->3 upgrade goes via 2.last and heavily publicising that is one way of dealing with my concern, but I think we've seen that we won't ever reach all our users, and I'd argue that this is a much more "obscure" requirement. People expect instability when something's versioned 0.x, but there's more expectation of stability when it's 1.x+.

edit: I think this is mostly opinion-based, so likely a resolution to this will come from a vote rather than one of us actually convincing the other.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@garrison I actually really liked the Julia approach of having a final minor version to introduce all the deprecations prior to the major version bump. It provided a concrete path to follow as a developer to get to working code despite introducing a lot of change in 1.0.

In general, I think relying upon the final minor version as a necessary step to expose all the deprecations is a very teachable system.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The notion of "final minor release" was introduced in 3ec912b


## Alternative Approaches
> Discuss other approaches to solving this problem and why these were not
> selected.

## Questions
> Open questions for discussion and an opening for feedback.

## Future Extensions
> Consider what extensions might spawn from this RFC. Discuss the roadmap of
> related projects and how these might interact. This section is also an opening
> for discussions and a great place to dump ideas.
>
> If you do not have any future extensions in mind, state that you cannot think
> of anything. This section should not be left blank.