From 0a9c67b63f2d0e410947a242d0718aa96c2c663c Mon Sep 17 00:00:00 2001 From: Mukundan Sundararajan <65565396+mukundansundar@users.noreply.github.com> Date: Wed, 12 Apr 2023 16:22:11 +0530 Subject: [PATCH 1/4] add API version progression guidelines Signed-off-by: Mukundan Sundararajan <65565396+mukundansundar@users.noreply.github.com> --- guides/api-design.md | 24 +++++++++++++++++++++++- templates/lifecycle.md | 14 ++++++++------ 2 files changed, 31 insertions(+), 7 deletions(-) diff --git a/guides/api-design.md b/guides/api-design.md index 058244d..9ad403d 100644 --- a/guides/api-design.md +++ b/guides/api-design.md @@ -103,9 +103,30 @@ Finally on addition of a new API, there may be addition of the capability to eit - Ensure successful execution of existing conformance and certification tests for any modified components +## Progression of API version to Stable + -## Progression of an API/Building block +Currently for HTTP API, the non-stable API has the path `v1.0-alpha1` instead of stable APIs having the form `v1.0`. Similarly for gRPC, the non-stable API has the suffix `Alpha1` added to the gRPC methods. +SDKs implementing the API before the stable release use the above mentioned paths/methods for HTTP and gRPC respectively. Once the API is promoted to stable, the SDKs must be updated to use the stable paths/methods. + +### Compatibility + +To cater to the scenario where an older SDK is accessing a newer version of Dapr, the following compatibility rules must be followed: +- If there are no breaking changes in the API(User request/response) from the prior version to the version it is made stable, then both the old and new paths/methods must be supported by the Dapr runtime. +- If there are breaking changes in the API(User request/response) from the prior version to the version it is made stable, then only the new paths/methods must be supported by the Dapr runtime. The old paths/methods must be removed from the Dapr runtime. + +> Note: The components themselves might have breaking changes, that will not affect the API version progression. + +Example Scenario: +Consider v3.0 of JS SDK supporting the Config API in Alpha stage and Dapr runtime v1.10. The Config API is promoted to Stable in v1.11 of the runtime. If between v1.10 Dapr and v1.11 Dapr runtime there are no breaking changes in the Config API then both Path/`v1.0-alpha1`/Method`Alpha1` and Path/`v1.0`/Method must be supported by the Dapr runtime. +Then the SDK can be updated independent of the runtime i.e. v3.0 version of JS SDK will still continue to work with the v1.11 runtime Config API. + +If there are breaking changes in the Config API then only Path/`v1.0`/Method must be supported by the Dapr runtime. In this case, the SDKs must be updated to use the new path/methods. In this case only the newer version of the SDK will work with the newer version of the runtime. + +> Note: This guidance is specifically for Dapr runtime SDK compatibility. SDKs may have their own way of exposing/differentiating between Alpha and Stable APIs. + +## Progression of an API/Building block ### Alpha to Beta In addition to the requirements that are required of any Alpha API, the following requirements must be met so that the API can graduate to Beta. For an API to be promoted to Beta, it must exist for at least one release cycle after its initial addition as Alpha. (i.e something added in 1.10 could become Beta in 1.12, having been stabilized through 1.11) @@ -131,6 +152,7 @@ For **building blocks** to progress, the following criteria are required: In addition to the requirements for a Beta API, the following requirements must be met so that the API can graduate to Stable. Similar to the previous phase change, this API must have been in the Beta phase for at least one full release _without any breaking changes_. In addition, the following criteria apply: +* Change API version based on the [API version progression guidelines](#progression-of-api-version-to-stable) * E2E scenarios must be well defined and comprehensive * Performance tests must be added(in case a new building block does not have performance tests in the Alpha/Beta stage)/updated * Expected performance data must be added to documentation diff --git a/templates/lifecycle.md b/templates/lifecycle.md index e33c678..f958c40 100644 --- a/templates/lifecycle.md +++ b/templates/lifecycle.md @@ -14,7 +14,7 @@ Links to any relevant resources go here: ## Alpha / Beta / Stable -For each stage, identify the expectations of this feature at that stage. For example, +For each stage, identify the expectations of this feature at that stage. For example, are there any performance issues, configuration changes or feature deprecation that will happen? * Anticipated performance / known limitations @@ -63,15 +63,17 @@ Additionally, for **building blocks**: Additionally, for **building blocks**: - [ ] Conformance tests updated to match any API changes that have been made -- [ ] Conformance tests exercise both positive and negative cases -- [ ] Minimum of N (three?) implementations of this building block -- [ ] Certification tests for implementations +- [ ] Conformance tests exercise both positive and negative cases +- [ ] Minimum of N (three?) implementations of this building block +- [ ] Certification tests for implementations - [ ] APIs that are used in the building block also meet Beta criteria -## Stable - +## Stable +- [ ] Change API version to stable. See [Stable API Versioning](../guides/api-design.md#progression-of-api-version-to-stable) + - [ ] HTTP `v1.0-suffix` to `v1.0` + - [ ] gRPC `MethodSuffix` to `Method` - [ ] Documentation is complete in `dapr/docs` with any changes since Beta - [ ] E2E scenarios well defined and comprehensive - [ ] Performance tests exist and regressions will prevent them from successfully passing From 56ee30e7d39f4ac17b0ff07eb2fb5b4d99730fb5 Mon Sep 17 00:00:00 2001 From: Mukundan Sundararajan <65565396+mukundansundar@users.noreply.github.com> Date: Wed, 12 Apr 2023 16:32:37 +0530 Subject: [PATCH 2/4] clarify when alpha suffixed paths will be removed Signed-off-by: Mukundan Sundararajan <65565396+mukundansundar@users.noreply.github.com> --- guides/api-design.md | 47 ++++++++++++++++++++++---------------------- 1 file changed, 23 insertions(+), 24 deletions(-) diff --git a/guides/api-design.md b/guides/api-design.md index 9ad403d..523b47d 100644 --- a/guides/api-design.md +++ b/guides/api-design.md @@ -81,38 +81,17 @@ _Backwards-**compatible** changes_ * May be proposed to _any_ API * Proposed changes to both the HTTP and gRPC API must be included - -## Requirements for Building Block changes - -Finally on addition of a new API, there may be addition of the capability to either an existing component or if it is a new building block, creation of a new set of components in the `dapr/components-contrib` repo. - -### Creating new API as part of a new building block in `dapr/components-contrib`** - -- Interfaces to be used by `dapr/dapr` code must be defined and agreed upon -- New building block package is defined in `components-contrib` repo, new code must only be added inside that building block package -- Conformance tests enable validating the components compliance with defined interface for the building block and creates a baseline for conformance testing any new components added. Conformance tests may be added for the new API with the understanding that it may evolve - - -### Creating new API for an existing building block in `dapr/components-contrib` - -- Interfaces changes for the new API must be defined and agreed upon -- Existing components that support the new API must be enhanced to be in compliance with the proposed interface as per the defined and agreed upon scope of the original proposal -- Conformance tests must be updated - - Get sign off on a basic suite of conformance tests for the interface method(s) - - Implement the suite of conformance tests as part of the existing suite of tests for the building block -- Ensure successful execution of existing conformance and certification tests for any modified components - - -## Progression of API version to Stable +### Progression of API version to Stable Currently for HTTP API, the non-stable API has the path `v1.0-alpha1` instead of stable APIs having the form `v1.0`. Similarly for gRPC, the non-stable API has the suffix `Alpha1` added to the gRPC methods. SDKs implementing the API before the stable release use the above mentioned paths/methods for HTTP and gRPC respectively. Once the API is promoted to stable, the SDKs must be updated to use the stable paths/methods. -### Compatibility +#### Compatibility To cater to the scenario where an older SDK is accessing a newer version of Dapr, the following compatibility rules must be followed: - If there are no breaking changes in the API(User request/response) from the prior version to the version it is made stable, then both the old and new paths/methods must be supported by the Dapr runtime. + - The `alpha` suffixed API paths/methods must be removed from the Dapr runtime once all _core_ SDKs have been updated (preferrably in the next Dapr release). Removal of the `alpha` suffixed API is still considered a breaking change and must be documented in the release notes as such. - If there are breaking changes in the API(User request/response) from the prior version to the version it is made stable, then only the new paths/methods must be supported by the Dapr runtime. The old paths/methods must be removed from the Dapr runtime. > Note: The components themselves might have breaking changes, that will not affect the API version progression. @@ -126,6 +105,26 @@ If there are breaking changes in the Config API then only Path/`v1.0`/Method mus > Note: This guidance is specifically for Dapr runtime SDK compatibility. SDKs may have their own way of exposing/differentiating between Alpha and Stable APIs. +## Requirements for Building Block changes + +Finally on addition of a new API, there may be addition of the capability to either an existing component or if it is a new building block, creation of a new set of components in the `dapr/components-contrib` repo. + +### Creating new API as part of a new building block in `dapr/components-contrib`** + +- Interfaces to be used by `dapr/dapr` code must be defined and agreed upon +- New building block package is defined in `components-contrib` repo, new code must only be added inside that building block package +- Conformance tests enable validating the components compliance with defined interface for the building block and creates a baseline for conformance testing any new components added. Conformance tests may be added for the new API with the understanding that it may evolve + + +### Creating new API for an existing building block in `dapr/components-contrib` + +- Interfaces changes for the new API must be defined and agreed upon +- Existing components that support the new API must be enhanced to be in compliance with the proposed interface as per the defined and agreed upon scope of the original proposal +- Conformance tests must be updated + - Get sign off on a basic suite of conformance tests for the interface method(s) + - Implement the suite of conformance tests as part of the existing suite of tests for the building block +- Ensure successful execution of existing conformance and certification tests for any modified components + ## Progression of an API/Building block ### Alpha to Beta From 4801ef8a572ca4ba668f49673be83706ee333b4c Mon Sep 17 00:00:00 2001 From: Mukundan Sundararajan <65565396+mukundansundar@users.noreply.github.com> Date: Thu, 17 Aug 2023 10:16:14 +0530 Subject: [PATCH 3/4] add changes for beta lifecycle stage also Signed-off-by: Mukundan Sundararajan <65565396+mukundansundar@users.noreply.github.com> --- guides/api-design.md | 21 ++++++++------------- 1 file changed, 8 insertions(+), 13 deletions(-) diff --git a/guides/api-design.md b/guides/api-design.md index 523b47d..cd56bb0 100644 --- a/guides/api-design.md +++ b/guides/api-design.md @@ -81,29 +81,24 @@ _Backwards-**compatible** changes_ * May be proposed to _any_ API * Proposed changes to both the HTTP and gRPC API must be included -### Progression of API version to Stable - +### Progression of API lifecycle to Stable -Currently for HTTP API, the non-stable API has the path `v1.0-alpha1` instead of stable APIs having the form `v1.0`. Similarly for gRPC, the non-stable API has the suffix `Alpha1` added to the gRPC methods. -SDKs implementing the API before the stable release use the above mentioned paths/methods for HTTP and gRPC respectively. Once the API is promoted to stable, the SDKs must be updated to use the stable paths/methods. +Currently for HTTP API, the alpha API has the path `v1.0-alpha1` and the beta API must have the path `v1.0-beta1` and the stable APIs must have the form `v1.0`. Similarly for gRPC, the alpha and beta APIs must have the suffix `Alpha1` or `Beta1` added to the gRPC methods. +SDKs implementing the API before the stable release use the above mentioned paths/methods for HTTP and gRPC respectively. Once the API is promoted to stable, the SDKs must be updated to use the stable paths/methods as soon as possible. #### Compatibility -To cater to the scenario where an older SDK is accessing a newer version of Dapr, the following compatibility rules must be followed: -- If there are no breaking changes in the API(User request/response) from the prior version to the version it is made stable, then both the old and new paths/methods must be supported by the Dapr runtime. - - The `alpha` suffixed API paths/methods must be removed from the Dapr runtime once all _core_ SDKs have been updated (preferrably in the next Dapr release). Removal of the `alpha` suffixed API is still considered a breaking change and must be documented in the release notes as such. -- If there are breaking changes in the API(User request/response) from the prior version to the version it is made stable, then only the new paths/methods must be supported by the Dapr runtime. The old paths/methods must be removed from the Dapr runtime. +For `alpha` to `beta` or `alpha` to `stable` or `beta` to `stable` progressions, the following rules must be followed: +- Once an API has progressed to "higher" stage be it `beta` or `stable` from `alpha`, the prior API endpoints (HTTP/gRPC) must be still supported together with the newer stage (`beta` or `stable`) API endpoints in Dapr runtime for atleast 1 release to give SDKs enough time to update to the new API endpoints. Functionality wise, there may be breaking changes between a API stage transitions, but both the prior API endpoint and the newer endpoint must point to the same same functionality once it has graduated to a particular stage. -> Note: The components themselves might have breaking changes, that will not affect the API version progression. +> Note: The components themselves might have breaking changes, that will not affect the API-SDK compatibility. Example Scenario: -Consider v3.0 of JS SDK supporting the Config API in Alpha stage and Dapr runtime v1.10. The Config API is promoted to Stable in v1.11 of the runtime. If between v1.10 Dapr and v1.11 Dapr runtime there are no breaking changes in the Config API then both Path/`v1.0-alpha1`/Method`Alpha1` and Path/`v1.0`/Method must be supported by the Dapr runtime. +Consider v3.0 of JS SDK supporting the Config API in Alpha stage and Dapr runtime v1.10. The Config API is promoted to Stable in v1.11 of the runtime. In this case both path `/v1.0-alpha1`, method`Alpha1` and path `/v1.0`, ,method without suffix must be supported by the Dapr runtime. Then the SDK can be updated independent of the runtime i.e. v3.0 version of JS SDK will still continue to work with the v1.11 runtime Config API. -If there are breaking changes in the Config API then only Path/`v1.0`/Method must be supported by the Dapr runtime. In this case, the SDKs must be updated to use the new path/methods. In this case only the newer version of the SDK will work with the newer version of the runtime. - -> Note: This guidance is specifically for Dapr runtime SDK compatibility. SDKs may have their own way of exposing/differentiating between Alpha and Stable APIs. +> Note: This guidance is specifically for Dapr runtime API-SDK compatibility. SDKs may have their own way of exposing/differentiating between Alpha and Stable APIs. ## Requirements for Building Block changes From 7138b9c2835b91dfc3a16570b59882430a7940c8 Mon Sep 17 00:00:00 2001 From: Mukundan Sundararajan <65565396+mukundansundar@users.noreply.github.com> Date: Thu, 17 Aug 2023 10:18:49 +0530 Subject: [PATCH 4/4] fix typo Signed-off-by: Mukundan Sundararajan <65565396+mukundansundar@users.noreply.github.com> --- guides/api-design.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/api-design.md b/guides/api-design.md index cd56bb0..93b7969 100644 --- a/guides/api-design.md +++ b/guides/api-design.md @@ -146,7 +146,7 @@ For **building blocks** to progress, the following criteria are required: In addition to the requirements for a Beta API, the following requirements must be met so that the API can graduate to Stable. Similar to the previous phase change, this API must have been in the Beta phase for at least one full release _without any breaking changes_. In addition, the following criteria apply: -* Change API version based on the [API version progression guidelines](#progression-of-api-version-to-stable) +* Change API version based on the [API version progression guidelines](#progression-of-api-lifecycle-to-stable) * E2E scenarios must be well defined and comprehensive * Performance tests must be added(in case a new building block does not have performance tests in the Alpha/Beta stage)/updated * Expected performance data must be added to documentation