From 472b58ab69e5a505566de58a1191cd7ee87dc7cb Mon Sep 17 00:00:00 2001 From: Luciano Bello Date: Wed, 26 Apr 2023 13:42:08 +0200 Subject: [PATCH 01/28] initial draft --- ####-release_cycle.md | 94 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 94 insertions(+) create mode 100644 ####-release_cycle.md diff --git a/####-release_cycle.md b/####-release_cycle.md new file mode 100644 index 0000000..2281d8d --- /dev/null +++ b/####-release_cycle.md @@ -0,0 +1,94 @@ +# RFC Title + +| **Status** | **Proposed/Accepted/Deprecated** | +|:------------------|:---------------------------------------------| +| **RFC #** | #### | +| **Authors** | [Luciano Bello](https://github.com/1ucian0/) | +| **Submitted** | 2023-04-26 | +| **Updated** | YYYY-MM-DD | + +## Summary +> One paragraph explanation of the feature. + +Qiskit release cycle had been in a process of stabilization with planned minor releases. +Thinking in a "beyond 0.x", what kind of release cycle would provide users with the tools for planning and stability while reduce the impact in the development workflow. + +## Motivation + +> - Why are we doing this? +> - What will this enable? +> - What will be the outcome? +> - Who will benefit? + +## User Benefit + +> - Who are the target users of this work? +> - How will users or contributors benefit from the work proposed? + +## 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 1month + todayMarker off + axisFormat %b-%Y + 0.17 :r017, 2021-04-01, 102d + 0.18 :r018, after r017, 147d + 0.19 :r019, after r018, 116d + 0.20 :r020, after r019, 91d + 0.21rc :r021rc, 2022-06-23, 7d + 0.21 :r021, after r020, 105d + 0.22rc :r022rc, 2022-10-07, 7d + 0.22 :r022, after r021, 105d + 0.23rc :r023rc, 2023-01-16, 10d + 0.23 :r024, after r022, 98d + 0.24rc :r024rc, 2023-04-20, 14d + 0.24 :milestone, 2023-05-04 +``` + +## Detailed Design + +> Technical reference level design. Elaborate on details such as: +> +> - Implementation procedure +> - If spans multiple projects cover these parts individually +> - Interaction with other features +> - Dissecting corner cases +> - Reference definition, eg., formal definitions. + +## 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. From 1bcf87b8abc809f4544ada9c053ef4e1bbd93bb4 Mon Sep 17 00:00:00 2001 From: Luciano Bello Date: Wed, 26 Apr 2023 13:49:50 +0200 Subject: [PATCH 02/28] gantt --- ####-release_cycle.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/####-release_cycle.md b/####-release_cycle.md index 2281d8d..fc973f3 100644 --- a/####-release_cycle.md +++ b/####-release_cycle.md @@ -54,17 +54,17 @@ gantt tickInterval 1month todayMarker off axisFormat %b-%Y - 0.17 :r017, 2021-04-01, 102d - 0.18 :r018, after r017, 147d - 0.19 :r019, after r018, 116d - 0.20 :r020, after r019, 91d - 0.21rc :r021rc, 2022-06-23, 7d - 0.21 :r021, after r020, 105d - 0.22rc :r022rc, 2022-10-07, 7d - 0.22 :r022, after r021, 105d - 0.23rc :r023rc, 2023-01-16, 10d - 0.23 :r024, after r022, 98d - 0.24rc :r024rc, 2023-04-20, 14d + 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 ``` From e5f34094e95c2259cad8574bb5e907a8b36a57da Mon Sep 17 00:00:00 2001 From: Luciano Bello Date: Wed, 26 Apr 2023 13:51:24 +0200 Subject: [PATCH 03/28] title --- ####-release_cycle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/####-release_cycle.md b/####-release_cycle.md index fc973f3..ca3e752 100644 --- a/####-release_cycle.md +++ b/####-release_cycle.md @@ -1,4 +1,4 @@ -# RFC Title +# Qiskit release cycle and versioning | **Status** | **Proposed/Accepted/Deprecated** | |:------------------|:---------------------------------------------| From e4eeb2ce4de477001db782a5fd45f2964d30a15d Mon Sep 17 00:00:00 2001 From: Luciano Bello Date: Wed, 26 Apr 2023 14:11:41 +0200 Subject: [PATCH 04/28] suggestion --- ####-release_cycle.md | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/####-release_cycle.md b/####-release_cycle.md index ca3e752..97ba2ed 100644 --- a/####-release_cycle.md +++ b/####-release_cycle.md @@ -51,7 +51,28 @@ Currently ```mermaid gantt dateFormat YYYY-MM-DD - tickInterval 1month + 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-%Y 0.17 :r017, 2021-04-01, 2021-07-12 From b625cd66e3f8a3e10d4be1f424c096eee30646d0 Mon Sep 17 00:00:00 2001 From: Luciano Bello Date: Thu, 27 Apr 2023 21:10:47 +0200 Subject: [PATCH 05/28] suggestion --- ####-release_cycle.md | 32 +++++++++++++++++++------------- 1 file changed, 19 insertions(+), 13 deletions(-) diff --git a/####-release_cycle.md b/####-release_cycle.md index 97ba2ed..5a19791 100644 --- a/####-release_cycle.md +++ b/####-release_cycle.md @@ -74,19 +74,25 @@ 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 + 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 From 87bbcee68a3b2ce74d57a3e6f1fb3e6b1232bf36 Mon Sep 17 00:00:00 2001 From: Luciano Bello Date: Sat, 13 May 2023 23:30:24 +0200 Subject: [PATCH 06/28] summary, motivation, and user benefits --- ####-release_cycle.md | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/####-release_cycle.md b/####-release_cycle.md index 5a19791..9f1182f 100644 --- a/####-release_cycle.md +++ b/####-release_cycle.md @@ -8,10 +8,9 @@ | **Updated** | YYYY-MM-DD | ## Summary -> One paragraph explanation of the feature. -Qiskit release cycle had been in a process of stabilization with planned minor releases. -Thinking in a "beyond 0.x", what kind of release cycle would provide users with the tools for planning and stability while reduce the impact in the development workflow. +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 @@ -20,10 +19,22 @@ Thinking in a "beyond 0.x", what kind of release cycle would provide users with > - 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. + * user support: users tend to demand longer support periods to avoid regular updates on their code and software. + * 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. + +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 -> - Who are the target users of this work? -> - How will users or contributors benefit from the work proposed? +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 From 299654b9faef7e32f3ad23cd21034f9f7a2aee17 Mon Sep 17 00:00:00 2001 From: Luciano Bello Date: Fri, 19 May 2023 17:39:41 +0200 Subject: [PATCH 07/28] adding deprecation comments from https://github.com/Qiskit/RFCs/pull/34#issuecomment-1549428294 --- ####-release_cycle.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/####-release_cycle.md b/####-release_cycle.md index 9f1182f..5476a59 100644 --- a/####-release_cycle.md +++ b/####-release_cycle.md @@ -116,6 +116,12 @@ gantt > - 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) + ## Alternative Approaches > Discuss other approaches to solving this problem and why these were not > selected. From 566e9b8d1d308b032c19ef8f1d402a2f9fce50ab Mon Sep 17 00:00:00 2001 From: Luciano Bello Date: Sun, 21 May 2023 09:33:57 +0200 Subject: [PATCH 08/28] title --- ####-release_cycle.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/####-release_cycle.md b/####-release_cycle.md index 5476a59..8a90fbc 100644 --- a/####-release_cycle.md +++ b/####-release_cycle.md @@ -117,10 +117,11 @@ gantt > - Reference definition, eg., formal definitions. -### Deprecations +### Deprecations and removals +* deprecation warnings cannot be introduced in patch releases * 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) +* deprecation warnings must be emitted for a complete major version (i.e. 1+ year) ## Alternative Approaches > Discuss other approaches to solving this problem and why these were not From 11b97b4e1d82e31313495f8ead54bbf6ab4f7ba9 Mon Sep 17 00:00:00 2001 From: Luciano Bello Date: Tue, 23 May 2023 11:29:00 +0200 Subject: [PATCH 09/28] current branch structure --- ####-release_cycle.md | 35 ++++++++++++++++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/####-release_cycle.md b/####-release_cycle.md index 8a90fbc..3fa5aad 100644 --- a/####-release_cycle.md +++ b/####-release_cycle.md @@ -57,7 +57,7 @@ The RFC aims to benefit users and Qiskit ecosystem developers, because they will > - Maintenance > - Compatibility -Currently +The current `0.*` release cycle increases the minor version in approximate periods of 3 months on a scheduled basis and, with the exception of the pre-release period (from one to two weeks) does not support more than one stable version at the time, i.e. the support of `0.X` finishes with the release of `0.X+1`. ```mermaid gantt @@ -79,6 +79,39 @@ gantt 0.24 :milestone, 2023-05-04 ``` +The `0.*` branch scheme is like this: + +```mermaid +gitGraph + commit id:"feature/0" + commit id: "ready_for_release" type:HIGHLIGHT + branch stable/0.X + commit id: "tag_0.X.0rc1" tag: "v0.X.0rc1" + checkout main + commit id:"bugfix/1" + checkout stable/0.X + cherry-pick id:"bugfix/1" + commit id: "tag_0.X.0" tag: "v0.X.0" + checkout main + commit id:"feature/1" + commit id:"feature/2" + commit id:"bugfix/2" + checkout stable/0.X + cherry-pick id:"bugfix/2" + checkout main + commit id:"feature/3" + commit id:"bugfix/3" + checkout stable/0.X + cherry-pick id:"bugfix/3" + checkout main + commit id:"feature/4" + checkout stable/0.X + commit id: "tag_0.X.1" tag: "v0.X.1" +``` + +The main branch is a single development branch from which some bugfixes are ported to the stable branch, from which releases are done. + + Suggest ```mermaid gantt From 24145f72f9b08e78f2a5572d4e8fc5abc3977525 Mon Sep 17 00:00:00 2001 From: Luciano Bello Date: Tue, 23 May 2023 12:22:33 +0200 Subject: [PATCH 10/28] X.4.* --- ####-release_cycle.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/####-release_cycle.md b/####-release_cycle.md index 3fa5aad..53ce8f7 100644 --- a/####-release_cycle.md +++ b/####-release_cycle.md @@ -124,19 +124,19 @@ gantt 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 + X.4.* :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 + X+1.4.* :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 + X+2.4.* :done, rX2Y3s, after rX2Y3, 183d ``` ## Detailed Design From 5e56c5136f1c22e78fc22f515fc40546a04cac42 Mon Sep 17 00:00:00 2001 From: Luciano Bello Date: Tue, 23 May 2023 13:13:57 +0200 Subject: [PATCH 11/28] should-haves of the suggested solution --- ####-release_cycle.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/####-release_cycle.md b/####-release_cycle.md index 53ce8f7..4207cb1 100644 --- a/####-release_cycle.md +++ b/####-release_cycle.md @@ -37,6 +37,7 @@ The starting date for the implementation of this RFC is, in principle, outside t 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 + -The current `0.*` release cycle increases the minor version in approximate periods of 3 months on a scheduled basis and, with the exception of the pre-release period (from one to two weeks) does not support more than one stable version at the time, i.e. the support of `0.X` finishes with the release of `0.X+1`. +The current *0.** release cycle increases the minor version in approximate periods of 3 months on a scheduled basis and, with the exception of the pre-release period (from one to two weeks) does not support more than one stable version at the time, i.e. the support of `0.X` finishes with the release of `0.X+1`. ```mermaid gantt @@ -112,7 +114,14 @@ gitGraph The main branch is a single development branch from which some bugfixes are ported to the stable branch, from which releases are done. -Suggest +The new release cycle could include: + + * [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) + * Critical bugfix support for a year or longer + * 6-month transition period for updating to a new major while having support. + * Non-breaking new features in a 3-month cycle (as currently) + + ```mermaid gantt dateFormat YYYY-MM-DD From b9fdb99ad19ed954b8c32a8b17d9f9d785b1c84d Mon Sep 17 00:00:00 2001 From: Luciano Bello Date: Sun, 4 Jun 2023 11:11:07 +0200 Subject: [PATCH 12/28] suggested gitGraph --- ####-release_cycle.md | 68 ++++++++++++++++++++++++++++++++++++++----- 1 file changed, 60 insertions(+), 8 deletions(-) diff --git a/####-release_cycle.md b/####-release_cycle.md index 4207cb1..7651d66 100644 --- a/####-release_cycle.md +++ b/####-release_cycle.md @@ -14,11 +14,6 @@ Balancing stable backward compatibility with the rapid pace of technology is a c ## 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: @@ -133,21 +128,78 @@ gantt X.1 :rX0Y1, after rX0Y0, 91d X.2 :rX0Y2, after rX0Y1, 91d X.3 :rX0Y3, after rX0Y2, 91d - X.4.* :done, X0Y3s, after rX0Y3, 183d + 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.4.* :done, rX1Y3s, after rX1Y3, 183d + 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.4.* :done, rX2Y3s, after rX2Y3, 183d + X+2.3.* :done, rX2Y3s, after rX2Y3, 183d ``` +Notice that there is no i.4, since it coincides with i+1.0. The period between October and January is the window where tracking changes are allowed into main. + +```mermaid +gitGraph + commit id:"feature/0" + commit id: "ready_for_X" type:HIGHLIGHT + branch stable/X.0 + commit id: "tag_X.0.0" tag: "vX.0.0" + checkout main + commit id:"bugfix/1" + checkout stable/X.0 + cherry-pick id:"bugfix/1" + checkout main + commit id:"feature/1" + checkout stable/X.0 + commit id: "tag_X.0.1" tag: "vX.0.1" + checkout main + commit id: "ready_for_1" type:HIGHLIGHT + branch "stable/X.1" + commit id: "tag_X.1" tag: "vX.1" + checkout main + commit id: "ready_for_2" type:HIGHLIGHT + branch "stable/X.2" + commit id: "tag_X.2" tag: "vX.2" + checkout main + commit id: "ready_for_3" type:HIGHLIGHT + branch "stable/X.3" + commit id: "tag_X.3.0" tag: "vX.3.0" + checkout main + commit id:"feature/2" + commit id:"bugfix/2" + checkout "stable/X.3" + cherry-pick id:"bugfix/2" + checkout main + commit id:"breaking/1" + + checkout stable/X.3 + commit id: "tag_X.3.1" tag: "vX.3.1" + + checkout main + commit id: "ready_for_plus_one" type:HIGHLIGHT + branch "stable/X+1.0" + commit id: "tag_X+1.0.0" tag: "vX+1.0.0" + + checkout main + commit id:"bugfix/3" + checkout "stable/X.3" + cherry-pick id:"bugfix/3" + checkout "stable/X+1.0" + cherry-pick id:"bugfix/3" + checkout "stable/X.3" + commit id: "tag_X.3.2" tag: "vX.3.2" + checkout "stable/X+1.0" + commit id: "tag_X+1.0.1" tag: "vX+1.0.1" +``` + + ## Detailed Design > Technical reference level design. Elaborate on details such as: From e401ee33dcca079e3c6c7588737fd214092d149d Mon Sep 17 00:00:00 2001 From: Luciano Bello Date: Sun, 4 Jun 2023 11:34:35 +0200 Subject: [PATCH 13/28] explanation --- ####-release_cycle.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/####-release_cycle.md b/####-release_cycle.md index 7651d66..26b6a8b 100644 --- a/####-release_cycle.md +++ b/####-release_cycle.md @@ -143,7 +143,7 @@ gantt X+2.3.* :done, rX2Y3s, after rX2Y3, 183d ``` -Notice that there is no i.4, since it coincides with i+1.0. The period between October and January is the window where tracking changes are allowed into main. +Notice that there is no i.4, since it coincides with i+1.0. ```mermaid gitGraph @@ -199,6 +199,9 @@ gitGraph commit id: "tag_X+1.0.1" tag: "vX+1.0.1" ``` +Similarly to the current branching model, non-breaking features (`feature/*`) and bug fixes (`bugfix/*`) can be merged into `main` at any point. Non-breaking features (`feature/*`) are released in minor releases, when branched out of `main` for `tag_X.*`. Bug fixes are cherry-picked from main into the respective `stable/X.*` branch. + +The main difference with the 0.* schema is that breaking changes cannot be introduced at any point, but only between the release of X.3.0 and X+1.0.0 (between October and January). ## Detailed Design From 49ad562a3458abd79b1fa042ffbbed99b155c155 Mon Sep 17 00:00:00 2001 From: Luciano Bello Date: Mon, 5 Jun 2023 15:47:24 +0200 Subject: [PATCH 14/28] stable --- ####-release_cycle.md | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/####-release_cycle.md b/####-release_cycle.md index 26b6a8b..eeaafff 100644 --- a/####-release_cycle.md +++ b/####-release_cycle.md @@ -127,23 +127,20 @@ gantt 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 + X.3 :done, rX0Y3, after rX0Y2, 274d section X+1.* - X+1.0 :rX1Y0, after rX0Y3, 91d + X+1.0 :rX1Y0, 2025-01-31, 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 + X+1.3 :done, rX1Y3, after rX1Y2, 274d section X+2.* - X+2.0 :rX2Y0, after rX1Y3, 91d + X+2.0 :rX2Y0, 2026-01-31, 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 + X+2.3 :done, rX2Y3s, after rX2Y2, 274d ``` -Notice that there is no i.4, since it coincides with i+1.0. +Notice that i.3 has an extra 6 month bug fixing support. There is no i.4, since it coincides with i+1.0, where new features (and possibly breaking changes) are released. ```mermaid gitGraph From 4233c9ae2173a4fae478cbc906b349f74d97f2e4 Mon Sep 17 00:00:00 2001 From: Luciano Bello Date: Wed, 22 Nov 2023 14:26:41 +0100 Subject: [PATCH 15/28] detailed --- ####-release_cycle.md | 73 +++++++++++++++++++++++++++++++++++-------- 1 file changed, 60 insertions(+), 13 deletions(-) diff --git a/####-release_cycle.md b/####-release_cycle.md index eeaafff..f7757cc 100644 --- a/####-release_cycle.md +++ b/####-release_cycle.md @@ -4,7 +4,7 @@ |:------------------|:---------------------------------------------| | **RFC #** | #### | | **Authors** | [Luciano Bello](https://github.com/1ucian0/) | -| **Submitted** | 2023-04-26 | +| **Submitted** | 2023-11-21 | | **Updated** | YYYY-MM-DD | ## Summary @@ -14,7 +14,7 @@ Balancing stable backward compatibility with the rapid pace of technology is a c ## Motivation -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. +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 first 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: @@ -202,20 +202,67 @@ The main difference with the 0.* schema is that breaking changes cannot be intro ## Detailed Design -> Technical reference level design. Elaborate on details such as: -> -> - Implementation procedure -> - If spans multiple projects cover these parts individually -> - Interaction with other features -> - Dissecting corner cases -> - Reference definition, eg., formal definitions. +### Definition of *public API* + +The Qiskit public API is considered +any documented module, class, function, or method that is not marked as private (with a `_` prefix). + +Exceptions: + + - Experimental interfaces: If module, class, function, or method is documented as experimental that is not marked as private (with a `_` prefix). + + +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) + + +### Versioning Model + +The proposed versioning model for Qiskit aligns with [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html), providing a clear and standardized approach to version numbering. This model aims to communicate the nature of changes on the public API in each release, helping users and developers understand the impact of an update at a glance. + +Semantic Versioning consists of three version components: *Major*, *Minor*, and *Patch* versions, represented as `X.Y.Z`. Each component has a specific meaning in the context of Qiskit: + +**Major Version (X):** Increments for backward-incompatible changes, indicating potential breaking changes that may require modifications in user code using the public API. When a new major version `X` is released: + +- There is a 18 month period for critical bugfixes. +- There might be non-breaking new features during that period. +- After 12 months `X+1` is released and a 6 month period for moving from `X` starts. +- After the release of `X+1`, `X` wont have new features and only critical bugfixes are provided. +- The features deprecated during the period of support with `X` will be removed in `X+1` +After the release of a major version (X.3.0), a 6-month bugfix support period is provided to address critical issues, ensuring stability for users during the transition to the next major release (X+1.0.0). + +**Minor Version (Y):** Increases for backward-compatible features or enhancements a new `X.Y` release: + +- Users can expect new functionalities without breaking existing code (with the exception of Experimental APIs +- Deprecation of previous functionality might be introduced (with a `Deprecation Warning` and documentation), pointing to the new prefer way or alternative, if there is one. +- The support of `X.Y` finishes with the release of `X.Y+1` in most of the cases (exception might apply) +**Patch Version (Z):** Bumps for backward-compatible bug fixes. -### Deprecations and removals +- New `Z` releases have no scheduled and they are done on a *need-base* considering: + - The *backportability* of the patch + - The severity of the bug to fix + - The criticality of the affected use-case +- Cannot be introduced in patch releases: + - new deprecation warnings + - new features of any kind + - raise minimum requirements for using or building Qiskit (including adding new dependencies) + - any kind of changes in any kind of public API (including Experimental APIs), including its removal or expansion. +- It may include: + - expansive support for new versions of Python, Rust, or run/build environment + - support for new versions of other existing dependencies +- The support of `X.Y.Z` finishes with the release of `X.Y.Z+1` (or `X.Y+1.0`) in most of the cases (exception might apply) +- After the release of `X+1`, bugfixing is provided via `X.Y.Z+N` in undetermined regularity for 6 months. -* deprecation warnings cannot be introduced in patch releases -* 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) +#### ## Alternative Approaches > Discuss other approaches to solving this problem and why these were not From 5915ae600e5680709b9f0f1baacfdb14fa5f88d8 Mon Sep 17 00:00:00 2001 From: Luciano Bello Date: Wed, 22 Nov 2023 16:49:38 +0100 Subject: [PATCH 16/28] definition of public api --- ####-release_cycle.md | 24 +++++++++--------------- 1 file changed, 9 insertions(+), 15 deletions(-) diff --git a/####-release_cycle.md b/####-release_cycle.md index f7757cc..3976712 100644 --- a/####-release_cycle.md +++ b/####-release_cycle.md @@ -205,23 +205,15 @@ The main difference with the 0.* schema is that breaking changes cannot be intro ### Definition of *public API* The Qiskit public API is considered -any documented module, class, function, or method that is not marked as private (with a `_` prefix). +any documented module, class, function, or method that is not marked as private (with a `_` prefix). **All the stability guarantees are on these *public APIs* and users are encourage to only use them.** -Exceptions: +**Exceptions**: - - Experimental interfaces: If module, class, function, or method is documented as experimental that is not marked as private (with a `_` prefix). - - -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 + - Experimental interfaces: If module, class, function, or method is documented as experimental that is not marked as private (with a `_` prefix). Experimental interfaces have to raise a user visible [Warning](https://docs.python.org/3/library/warnings.html) (exact Warning type to be define). + - Abstract interface definitions: These APIs are created to define an interface to be implemented by a subclass. Methods and properties defined as private in these Abstract classes are part of the public API. + - Low-level methods for advanced usage: There are private 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 canonical example of this is the `QuantumCircuit._append` method). ### Versioning Model @@ -262,7 +254,9 @@ After the release of a major version (X.3.0), a 6-month bugfix support period is - The support of `X.Y.Z` finishes with the release of `X.Y.Z+1` (or `X.Y+1.0`) in most of the cases (exception might apply) - After the release of `X+1`, bugfixing is provided via `X.Y.Z+N` in undetermined regularity for 6 months. -#### +### Git branching model + +TODO ## Alternative Approaches > Discuss other approaches to solving this problem and why these were not From 8302fa7b481b7fb01a5fc9e860153e86c9fe7e5f Mon Sep 17 00:00:00 2001 From: Luciano Bello Date: Tue, 28 Nov 2023 16:33:43 +0100 Subject: [PATCH 17/28] branching --- ####-release_cycle.md | 51 +++++++++++++++++++++++++++++++++++-------- 1 file changed, 42 insertions(+), 9 deletions(-) diff --git a/####-release_cycle.md b/####-release_cycle.md index 3976712..4447d38 100644 --- a/####-release_cycle.md +++ b/####-release_cycle.md @@ -24,9 +24,6 @@ However, there is a demand for a more transparent release cycle with longer peri 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. @@ -143,30 +140,57 @@ gantt Notice that i.3 has an extra 6 month bug fixing support. There is no i.4, since it coincides with i+1.0, where new features (and possibly breaking changes) are released. ```mermaid +%%{init: {'theme': 'default', 'gitGraph': {'mainBranchOrder': 1}} }%% gitGraph commit id:"feature/0" commit id: "ready_for_X" type:HIGHLIGHT - branch stable/X.0 + branch "next/X+1" order: 0 + + commit id:"breaking/0" + checkout main + + branch stable/X.0 order: 2 commit id: "tag_X.0.0" tag: "vX.0.0" checkout main commit id:"bugfix/1" checkout stable/X.0 cherry-pick id:"bugfix/1" + + checkout "next/X+1" + commit id:"breaking/2" + commit id:"breaking/3" + checkout main commit id:"feature/1" checkout stable/X.0 commit id: "tag_X.0.1" tag: "vX.0.1" + checkout main commit id: "ready_for_1" type:HIGHLIGHT - branch "stable/X.1" + + checkout "next/X+1" + merge "main" + checkout main + + branch "stable/X.1" order: 2 commit id: "tag_X.1" tag: "vX.1" checkout main commit id: "ready_for_2" type:HIGHLIGHT - branch "stable/X.2" + + checkout "next/X+1" + merge "main" + checkout main + + branch "stable/X.2" order: 2 commit id: "tag_X.2" tag: "vX.2" checkout main commit id: "ready_for_3" type:HIGHLIGHT - branch "stable/X.3" + + checkout "next/X+1" + merge "main" + checkout main + + branch "stable/X.3" order: 2 commit id: "tag_X.3.0" tag: "vX.3.0" checkout main commit id:"feature/2" @@ -179,9 +203,15 @@ gitGraph checkout stable/X.3 commit id: "tag_X.3.1" tag: "vX.3.1" + checkout "next/X+1" + commit id:"breaking/4" + commit id:"breaking/5" + checkout main - commit id: "ready_for_plus_one" type:HIGHLIGHT - branch "stable/X+1.0" + merge "next/X+1" + + commit id: "ready_for_X+1" type:HIGHLIGHT + branch "stable/X+1.0" order: 2 commit id: "tag_X+1.0.0" tag: "vX+1.0.0" checkout main @@ -258,6 +288,8 @@ After the release of a major version (X.3.0), a 6-month bugfix support period is TODO + + \ No newline at end of file From 23dc1c2ff3c88073b9bbacad8472bb715999e9ec Mon Sep 17 00:00:00 2001 From: Luciano Bello Date: Mon, 11 Dec 2023 14:58:42 +0100 Subject: [PATCH 18/28] upgrade path --- ####-release_cycle.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/####-release_cycle.md b/####-release_cycle.md index 4447d38..d1fe31e 100644 --- a/####-release_cycle.md +++ b/####-release_cycle.md @@ -3,7 +3,7 @@ | **Status** | **Proposed/Accepted/Deprecated** | |:------------------|:---------------------------------------------| | **RFC #** | #### | -| **Authors** | [Luciano Bello](https://github.com/1ucian0/) | +| **Authors** | [Luciano Bello](https://github.com/1ucian0/) | | **Submitted** | 2023-11-21 | | **Updated** | YYYY-MM-DD | @@ -288,6 +288,18 @@ After the release of a major version (X.3.0), a 6-month bugfix support period is TODO + * Removals/breaking changes can be PRed at any point against `next/X+1` branch. + * Regularly, `main` should be merge into `next/X+1` to keep it up-to-date. The suggestion is for every minor release, at least. + + +### Suggested upgrade path + +Users should upgrade minors and patch versions as soon as the next stable release happens in every case, except when there is a new major release. +Major releases allow for 6 months to transition from `X` to `X+1`. +Users and downstreamers should depend on `=X.Y, Date: Mon, 11 Dec 2023 16:05:56 +0100 Subject: [PATCH 19/28] branching model --- ####-release_cycle.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/####-release_cycle.md b/####-release_cycle.md index d1fe31e..ee17e45 100644 --- a/####-release_cycle.md +++ b/####-release_cycle.md @@ -286,10 +286,16 @@ After the release of a major version (X.3.0), a 6-month bugfix support period is ### Git branching model -TODO +Before the release of a major `X.0`, the last minor `X-1.Y` should be tagged in the `stable/X-1.Y`. Two weeks before the release `X.0` the branch `next/X` should be merged into `main` (probably not necessary the first time). Then `stable/X.0` is branched from `main`, as well as `next/X+1`. In `stable/X.0`, `X.0.0rc1` is tagged and release. Two week later, at stable release time, `X.0.0` is tagged on `stable/X.0` and released. - * Removals/breaking changes can be PRed at any point against `next/X+1` branch. - * Regularly, `main` should be merge into `next/X+1` to keep it up-to-date. The suggestion is for every minor release, at least. +Similarly, two week before the release of `Y` minor, a `stable/X.Y` branch from `main` is created, from where `X.Y.0rc1` is tagged. When stable `X.Y.0` will be released (two weeks later), the label is on `stable/X.Y`. + +All changes, including bug fixes, with backward compatibility are PRed with `main` as base. Bugfix PRs that are possible to port to stable should be tagged as `stable-backport-potential` and a bot ports them to `stable/X.Y` (where `Y` is the last minor). +At undefined time, a new patch release `X.Y.Z` is tagged on `stable/X.Y` and released. + +Non-backward compatible changes, including removal of deprecated code, can be PRed at any point against `next/X+1` branch. + +Regularly, `main` should be merge into `next/X+1` to keep it up-to-date. The suggestion is for every minor release, at least. ### Suggested upgrade path From a8a6fcce56dcfde5056f9e9be91de97f32c0e9ae Mon Sep 17 00:00:00 2001 From: Luciano Bello Date: Fri, 1 Mar 2024 12:52:14 +0100 Subject: [PATCH 20/28] Update ####-release_cycle.md Co-authored-by: Matthew Treinish --- ####-release_cycle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/####-release_cycle.md b/####-release_cycle.md index ee17e45..43c6324 100644 --- a/####-release_cycle.md +++ b/####-release_cycle.md @@ -14,7 +14,7 @@ Balancing stable backward compatibility with the rapid pace of technology is a c ## Motivation -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 first 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. +Qiskit is known for its dynamic nature and frequent deprecation of features. However, the [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 first notification point on) when removing a feature. For the past several years Qiskit has also had planned releases on a regular schedule for mitigating the impact of coming changes, as well as pre-releases to enable testing prior to a final release. 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: From c7a5fb84161c11c783c12afbce0c5c87a759e963 Mon Sep 17 00:00:00 2001 From: Luciano Bello Date: Fri, 1 Mar 2024 12:52:49 +0100 Subject: [PATCH 21/28] Update ####-release_cycle.md Co-authored-by: Matthew Treinish --- ####-release_cycle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/####-release_cycle.md b/####-release_cycle.md index 43c6324..dff0234 100644 --- a/####-release_cycle.md +++ b/####-release_cycle.md @@ -111,7 +111,7 @@ The new release cycle could include: * [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) * Critical bugfix support for a year or longer * 6-month transition period for updating to a new major while having support. - * Non-breaking new features in a 3-month cycle (as currently) + * Non-breaking new features releases in a 3-month cycle (as currently) ```mermaid From ee82646fe39f8a05897c20dfa25e6cbc8d55535c Mon Sep 17 00:00:00 2001 From: Luciano Bello Date: Fri, 1 Mar 2024 12:54:35 +0100 Subject: [PATCH 22/28] Apply suggestions from code review Co-authored-by: Matthew Treinish --- ####-release_cycle.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/####-release_cycle.md b/####-release_cycle.md index dff0234..71a795f 100644 --- a/####-release_cycle.md +++ b/####-release_cycle.md @@ -18,9 +18,9 @@ Qiskit is known for its dynamic nature and frequent deprecation of features. How 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. - * user support: users tend to demand longer support periods to avoid regular updates on their code and software. - * 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. + * developer effort: Supporting several stable versions requires significant development resources. At the same time, rolling releases tend to create technical debt and fewer chances to enable re-architecting features or interfaces for better maintainability or changing needs. + * user support: users tend to demand longer support periods to avoid regular updates in their code and software. + * new feature support for coming technology: the quantum computing field and hardware is constantly changing and scaling up. This can require changes in Qiskit,which are not always compatible with previous approaches. 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. @@ -103,13 +103,13 @@ gitGraph commit id: "tag_0.X.1" tag: "v0.X.1" ``` -The main branch is a single development branch from which some bugfixes are ported to the stable branch, from which releases are done. +The main branch is a single development branch from which some bugfixes are backported to the stable branch, from which releases are done. -The new release cycle could include: +The new release cycle will include: * [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) - * Critical bugfix support for a year or longer + * Critical bugfix support for at least one year * 6-month transition period for updating to a new major while having support. * Non-breaking new features releases in a 3-month cycle (as currently) @@ -124,20 +124,20 @@ gantt X.0 :rX0Y0, 2024-01-31, 91d X.1 :rX0Y1, after rX0Y0, 91d X.2 :rX0Y2, after rX0Y1, 91d - X.3 :done, rX0Y3, after rX0Y2, 274d + X.3 :rX0Y3, after rX0Y2, 91d + X.4, :done, rX0Y4, after rX0Y3, 183d section X+1.* X+1.0 :rX1Y0, 2025-01-31, 91d X+1.1 :rX1Y1, after rX1Y0, 91d X+1.2 :rX1Y2, after rX1Y1, 91d - X+1.3 :done, rX1Y3, after rX1Y2, 274d + X+1.3 : rX1Y3 after X1Y2, 91d + X+1.4, :done, rX1Y4, after rX1Y3, 183d section X+2.* X+2.0 :rX2Y0, 2026-01-31, 91d X+2.1 :rX2Y1, after rX2Y0, 91d X+2.2 :rX2Y2, after rX2Y1, 91d - X+2.3 :done, rX2Y3s, after rX2Y2, 274d -``` - -Notice that i.3 has an extra 6 month bug fixing support. There is no i.4, since it coincides with i+1.0, where new features (and possibly breaking changes) are released. + X+2.3 :rX2Y3s, after rX2Y2, 91d + X+1.4, :done, rX2Y4, after rX2Y3, 183d ```mermaid %%{init: {'theme': 'default', 'gitGraph': {'mainBranchOrder': 1}} }%% From 3ec912ba0ae7e5664cdc03692f45ac9506caefea Mon Sep 17 00:00:00 2001 From: Luciano Bello Date: Sun, 3 Mar 2024 15:55:57 +0100 Subject: [PATCH 23/28] final minor release --- ####-release_cycle.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/####-release_cycle.md b/####-release_cycle.md index 71a795f..28eada6 100644 --- a/####-release_cycle.md +++ b/####-release_cycle.md @@ -3,9 +3,8 @@ | **Status** | **Proposed/Accepted/Deprecated** | |:------------------|:---------------------------------------------| | **RFC #** | #### | -| **Authors** | [Luciano Bello](https://github.com/1ucian0/) | +| **Authors** | [Luciano Bello](https://github.com/1ucian0/) and the Qiskit development team | | **Submitted** | 2023-11-21 | -| **Updated** | YYYY-MM-DD | ## Summary @@ -263,9 +262,14 @@ After the release of a major version (X.3.0), a 6-month bugfix support period is **Minor Version (Y):** Increases for backward-compatible features or enhancements a new `X.Y` release: -- Users can expect new functionalities without breaking existing code (with the exception of Experimental APIs -- Deprecation of previous functionality might be introduced (with a `Deprecation Warning` and documentation), pointing to the new prefer way or alternative, if there is one. +- Minor releases are planned for every 3 months, on a best effort basis. +- Users can expect new functionalities without breaking existing code (with the exception of Experimental APIs. +- Significant refactorings of internals without changes in the public API are possible in minor releases. +- Bugfixing without changes in the public API are possible in minor releases. +- Deprecation of previous functionality might be introduced (with a `DeprecationWarning` and documentation), pointing to the new prefer way or alternative, if there is one. - The support of `X.Y` finishes with the release of `X.Y+1` in most of the cases (exception might apply) +- The minor release before the next major (aka, *final minor release*) has support for 6 months after the next major. That is, if `X.Y` is the last feature release before `X+1.0`, then `X.Y+1` is the final minor release. +- The final minor release `X.Y+1` should not have new features but might include `DeprecationWarning`s that will be removed in the next major, `X+1.0`. **Patch Version (Z):** Bumps for backward-compatible bug fixes. From d117b2cbea13fa28e6098cdc65ab42a9ef6d1c51 Mon Sep 17 00:00:00 2001 From: Luciano Bello Date: Sun, 3 Mar 2024 16:37:58 +0100 Subject: [PATCH 24/28] QPY --- ####-release_cycle.md | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/####-release_cycle.md b/####-release_cycle.md index 28eada6..0ed1bf1 100644 --- a/####-release_cycle.md +++ b/####-release_cycle.md @@ -19,7 +19,7 @@ However, there is a demand for a more transparent release cycle with longer peri * developer effort: Supporting several stable versions requires significant development resources. At the same time, rolling releases tend to create technical debt and fewer chances to enable re-architecting features or interfaces for better maintainability or changing needs. * user support: users tend to demand longer support periods to avoid regular updates in their code and software. - * new feature support for coming technology: the quantum computing field and hardware is constantly changing and scaling up. This can require changes in Qiskit,which are not always compatible with previous approaches. + * new feature support for coming technology: the quantum computing field and hardware is constantly changing and scaling up. This can require changes in Qiskit, which are not always compatible with previous approaches. 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. @@ -50,7 +50,7 @@ The RFC aims to benefit users and Qiskit ecosystem developers, because they will > - Compatibility --> -The current *0.** release cycle increases the minor version in approximate periods of 3 months on a scheduled basis and, with the exception of the pre-release period (from one to two weeks) does not support more than one stable version at the time, i.e. the support of `0.X` finishes with the release of `0.X+1`. +The current `0.*`-release cycle increases the minor version in approximate periods of 3 months on a scheduled basis and, with the exception of the pre-release period (from one to two weeks) does not support more than one stable version at the time, i.e. the support of `0.X` finishes with the release of `0.X+1`. ```mermaid gantt @@ -72,7 +72,7 @@ gantt 0.24 :milestone, 2023-05-04 ``` -The `0.*` branch scheme is like this: +The `0.*`-release branch scheme is like this: ```mermaid gitGraph @@ -227,14 +227,15 @@ gitGraph Similarly to the current branching model, non-breaking features (`feature/*`) and bug fixes (`bugfix/*`) can be merged into `main` at any point. Non-breaking features (`feature/*`) are released in minor releases, when branched out of `main` for `tag_X.*`. Bug fixes are cherry-picked from main into the respective `stable/X.*` branch. -The main difference with the 0.* schema is that breaking changes cannot be introduced at any point, but only between the release of X.3.0 and X+1.0.0 (between October and January). +The main difference with the `0.*`-release schema is that breaking changes cannot be introduced at any point, but only between major releases (for example, from `X.Y.Z` to `X+1.0.0`. ## Detailed Design +All the stability guarantees on this RFC are on *public APIs*. Users and developers are encourage to only use public API and do not hook on internal interfaces. + ### Definition of *public API* -The Qiskit public API is considered -any documented module, class, function, or method that is not marked as private (with a `_` prefix). **All the stability guarantees are on these *public APIs* and users are encourage to only use them.** +The Qiskit public API is considered any documented module, class, function, or method that is not marked as private (with a `_` prefix). **Exceptions**: @@ -251,14 +252,14 @@ The proposed versioning model for Qiskit aligns with [Semantic Versioning 2.0.0] Semantic Versioning consists of three version components: *Major*, *Minor*, and *Patch* versions, represented as `X.Y.Z`. Each component has a specific meaning in the context of Qiskit: -**Major Version (X):** Increments for backward-incompatible changes, indicating potential breaking changes that may require modifications in user code using the public API. When a new major version `X` is released: +**Major Version (X):** Increments for backward-incompatible changes, indicating potential breaking changes that may require modifications in user code using the public API. -- There is a 18 month period for critical bugfixes. -- There might be non-breaking new features during that period. -- After 12 months `X+1` is released and a 6 month period for moving from `X` starts. -- After the release of `X+1`, `X` wont have new features and only critical bugfixes are provided. -- The features deprecated during the period of support with `X` will be removed in `X+1` -After the release of a major version (X.3.0), a 6-month bugfix support period is provided to address critical issues, ensuring stability for users during the transition to the next major release (X+1.0.0). +- A major version `X` release has a minimum of 18 month period for support with critical bug fixes. +- New major release `X` can introduce breaking changes with respect to previous major release `X-1`. +- During the `X` release series, there might include non-breaking new features during that period. +- After the release of a major release `X`, `X+1` can be released after, at least, 12 months. +- After the release of `X+1`, `X` wont have new features and only critical bugfixes are provided for, at least, 6 months. +- The features deprecated during the period of support with `X` will be removed in `X+1` **Minor Version (Y):** Increases for backward-compatible features or enhancements a new `X.Y` release: @@ -301,6 +302,9 @@ Non-backward compatible changes, including removal of deprecated code, can be PR Regularly, `main` should be merge into `next/X+1` to keep it up-to-date. The suggestion is for every minor release, at least. +### QPY support + +A new major release `X` has support to dump on QPY in the same version than the final minor version `X-1`. This allows `X` to dump QPY that can be loaded with `X-1`. Minor releases can increase the version of QPY but should always support the QPY version in the final minor release of `X-1` until the end-of-life of `X-1`. ### Suggested upgrade path From ddfc67122249c5f1301fbe21a8a92195a293c94a Mon Sep 17 00:00:00 2001 From: Luciano Bello Date: Sun, 3 Mar 2024 21:36:46 +0100 Subject: [PATCH 25/28] mermeid fix --- ####-release_cycle.md | 1 + 1 file changed, 1 insertion(+) diff --git a/####-release_cycle.md b/####-release_cycle.md index 0ed1bf1..8dc1463 100644 --- a/####-release_cycle.md +++ b/####-release_cycle.md @@ -137,6 +137,7 @@ gantt X+2.2 :rX2Y2, after rX2Y1, 91d X+2.3 :rX2Y3s, after rX2Y2, 91d X+1.4, :done, rX2Y4, after rX2Y3, 183d +``` ```mermaid %%{init: {'theme': 'default', 'gitGraph': {'mainBranchOrder': 1}} }%% From f54ad29748cd1dfc053c71ad16e87d2387f5347a Mon Sep 17 00:00:00 2001 From: Luciano Bello Date: Sun, 3 Mar 2024 21:42:14 +0100 Subject: [PATCH 26/28] mermeid gantt fix --- ####-release_cycle.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/####-release_cycle.md b/####-release_cycle.md index 8dc1463..7e978be 100644 --- a/####-release_cycle.md +++ b/####-release_cycle.md @@ -129,14 +129,14 @@ gantt X+1.0 :rX1Y0, 2025-01-31, 91d X+1.1 :rX1Y1, after rX1Y0, 91d X+1.2 :rX1Y2, after rX1Y1, 91d - X+1.3 : rX1Y3 after X1Y2, 91d + X+1.3 :rX1Y3, after rX1Y2, 91d X+1.4, :done, rX1Y4, after rX1Y3, 183d section X+2.* X+2.0 :rX2Y0, 2026-01-31, 91d X+2.1 :rX2Y1, after rX2Y0, 91d X+2.2 :rX2Y2, after rX2Y1, 91d X+2.3 :rX2Y3s, after rX2Y2, 91d - X+1.4, :done, rX2Y4, after rX2Y3, 183d + X+2.4, :done, rX2Y4, after rX2Y3s, 183d ``` ```mermaid From f61a2336f3e146fb59d3f940605b977bcc70f56e Mon Sep 17 00:00:00 2001 From: Luciano Bello Date: Sun, 3 Mar 2024 21:53:04 +0100 Subject: [PATCH 27/28] Feature, Deprecation, and Removal Proposal Deadline --- ####-release_cycle.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/####-release_cycle.md b/####-release_cycle.md index 7e978be..9167543 100644 --- a/####-release_cycle.md +++ b/####-release_cycle.md @@ -306,6 +306,15 @@ Regularly, `main` should be merge into `next/X+1` to keep it up-to-date. The sug ### QPY support A new major release `X` has support to dump on QPY in the same version than the final minor version `X-1`. This allows `X` to dump QPY that can be loaded with `X-1`. Minor releases can increase the version of QPY but should always support the QPY version in the final minor release of `X-1` until the end-of-life of `X-1`. + +### Pre-releases + +The pre-release model from the `0.*`-release cycle will continue in the same way. Two weeks before the release of a minor `X.Y`, a release candidate `X.Yrc0` will be released as a pre-release. The final minor release might be except for that release candidate release, as it does not include new features. + +### Feature, deprecation, and removal proposal deadline + +Two weeks before the pre-release or a minor release, what ever is before, there will be a feature, deprecation, and removal proposal deadline. That means that any PR with addition, removal, or modification on the public API needs to be ready for review in the Qiskit repository before that date. Exceptions might apply at consideration of the Qiskit core team. + ### Suggested upgrade path From a8d09719700055c77d866ce632602f3db10967a5 Mon Sep 17 00:00:00 2001 From: Luciano Bello Date: Tue, 5 Mar 2024 13:55:29 +0100 Subject: [PATCH 28/28] Update ####-release_cycle.md Co-authored-by: Matthew Treinish --- ####-release_cycle.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/####-release_cycle.md b/####-release_cycle.md index 9167543..de35b47 100644 --- a/####-release_cycle.md +++ b/####-release_cycle.md @@ -305,7 +305,17 @@ Regularly, `main` should be merge into `next/X+1` to keep it up-to-date. The sug ### QPY support -A new major release `X` has support to dump on QPY in the same version than the final minor version `X-1`. This allows `X` to dump QPY that can be loaded with `X-1`. Minor releases can increase the version of QPY but should always support the QPY version in the final minor release of `X-1` until the end-of-life of `X-1`. +The QPY serialization format is backwards compatible so that a new Qiskit can release can always load a QPY +file generated with an earlier release of Qiskit. However, the format isn't forward compatible, so it's not possible +to load QPY files generated with newer version of Qiskit using an older release. To support compatibility across major version releases, the `qiskit.qpy.dump()` function has an optional argument `version` that lets a user specify a back version of the QPY format emitted by the `dump()` function. There are two constants exposed by +the `qpy` module, `qiskit.qpy.QPY_VERSION` which documents the default format version emitted by `dump()` and +also the maximum version that `load()` supports, and `qiskit.qpy.QPY_COMPATIBILITY_VERSION` which documents the minimum version that `dump()` can emit (while `load()` can load any version <= `QPY_VERSION`). + +To facilitate user migration across major version releases the `qiskit.qpy.dump()` function will always support at least one overlapping version between the `X.0.0` and the `X-1.Y.0` release (where Y is the last minor version of +that series). This will enable saving QPY format files that can be loaded by both major versions from the newer +release. For example, in Qiskit 1.0.0 the `QPY_VERSION` was `11`, and in Qiskit 0.46.0 the `QPY_VERSION` constant was `10`. For qiskit 1.0.0 the minimum version supported by `dump()`'s `version` argument, and exposed by +`qiskit.qpy.QPY_COMPATIBILITY_VERSION` was 10. This enabled Qiskit 1.0.0 to generate qpy payloads that could +be loaded by Qiskit 0.46.0. ### Pre-releases