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