Proposal: API and SDK version labeling #280
Conversation
tigrannajaryan
requested review from
AloisReitbauer,
bogdandrutu,
c24t,
carlosalberto,
iredelmeier,
reyang,
SergeyKanzhelev,
songy23,
tedsuo and
yurishkuro
as code owners
specification/library-guidelines.md
Outdated
| @@ -85,6 +85,16 @@ Note that mocking is also possible by using SDK and a Mock `Exporter` without ne | |||
|
|
|||
| The mocking approach chosen will depend on the testing goals and at which point exactly it is desirable to intercept the telemetry data path during the test. | |||
|
|
|||
| ## Version Labeling | |||
|
|
|||
| SDK must use semantic version numbering. SDK version number and version number of API that SDK implements can be different. SDK MUST be labeled with its own version number with one limitation: major version number of the SDK must be the same as the major version number of the API that the SDK implements. | |||
There was a problem hiding this comment.
I am confused about API and SDK.
I think there are 3 components here:
Specs - version
API (library artifact that includes only the API definition) - version
SDK (library artifact that includes the default implementation for the API) - version
Can we clarify this in what you wrote? I have a feeling that API in this text refers to Specs.
There was a problem hiding this comment.
Is there a difference between API version and Spec version? API package 0.1.0 must implement Spec version 0.1.0. Do we have the need to make these 2 different?
There was a problem hiding this comment.
I think we need to keep the API artifact and SDK in sync but those will not be in sync with Specs.
Imagine we start some parts of the v0.2 specs implementation which change the API add a new class. SDK will no longer work with the previous API because will try to implement a class that does not exist.
So I think API and SDK will always be released together and independent of the specs version
There was a problem hiding this comment.
@bogdandrutu your last statement applies to the default SDK, but this document applies to any SDK.
There was a problem hiding this comment.
I think we need to keep the API artifact and SDK in sync but those will not be in sync with Specs.
@bogdandrutu I would expect that API artifact and Spec are in sync. The API artifact does not need to be re-released everytime you make a change in the SDK and make an SDK release if the SDK implements the same version of the spec.
API artifact needs to be re-released only when new spec version is created and the corresponding API artifact is created.
Imagine we start some parts of the v0.2 specs implementation which change the API add a new class. SDK will no longer work with the previous API because will try to implement a class that does not exist.
I do not fully get this example. My vision for Spec/API/SDK release timeline is the following:
- Spec v0.1.0 is defined.
- Language library authors read the spec and create API artifact v0.1.0. The artifact matches the spec v0.1.0.
- Language library authors create SDK v0.1.0. The SDK implements API/Spec v0.1.0.
- Language library authors continue working and make a new SDK release v0.1.1, then another release v0.2.0 and then another v0.2.1. All these SDKs implement API/Spec v0.1.0 and must be used together with API artifact v0.1.0. No new API artifacts are released.
- Spec v0.2.0 is defined.
- Language library authors read the spec and create API artifact v0.2.0. The artifact matches the spec v0.2.0.
- Language library authors create SDK v0.3.0. The SDK implements API/Spec v0.2.0.
- Language library authors continue working and make a new SDK release v0.3.1, then another release v0.3.2 and then another v0.4.0. All these SDKs implement API/Spec v0.2.0 and must be used together with API artifact v0.2.0. No new API artifacts are released.
and so on…
There was a problem hiding this comment.
I like @bogdandrutu suggestion on being more explicit on what this note addresses - spec or actuarial libraries. But I think by itself this PR brings more clarity
specification/library-guidelines.md
Outdated
| @@ -85,6 +85,16 @@ Note that mocking is also possible by using SDK and a Mock `Exporter` without ne | |||
|
|
|||
| The mocking approach chosen will depend on the testing goals and at which point exactly it is desirable to intercept the telemetry data path during the test. | |||
|
|
|||
| ## Version Labeling | |||
|
|
|||
| SDK must use semantic version numbering. SDK version number and version number of API that SDK implements can be different. SDK MUST be labeled with its own version number with one limitation: major version number of the SDK must be the same as the major version number of the API that the SDK implements. | |||
There was a problem hiding this comment.
@bogdandrutu your last statement applies to the default SDK, but this document applies to any SDK.
|
I think it is very hard to make only one API release for a spec version:
I think because 1 and 2 we cannot keep the API in sync with Specs. |
|
The motivation against completely decoupled versioning seems very slim, referring to some possible hypothetical use case in the future. I think there is enough prior art, at least in the OpenTracing project, to demonstrate that all three versions, spec, API, and SDK, need to be decoupled. |
@bogdandrutu I understand now. Makes sense. So, basically it means we will have 3 different versions to deal with:
Note: SDK packages are labeled with API package version they correspond to, not with Spec version that they implement. This is important because different API packages that implement the same Spec version may be incompatible from internal implementation perspective with the SDK releases. This should be rare but it is still a possibility (because internal ABI between API and SDK is not defined in the Spec and language library authors must be free to modify internal ABI as needed). Does this sound right? |
@yurishkuro is this an argument for getting rid of the requirement to have the same major version number or you are asking to have 3 different version numbers?
Yes, makes sense. Please see my previous comment in this thread, let me know if it correctly captures the idea. |
|
@tigrannajaryan yes, previous comment looks good, except for this sentence in item 3: "Must have the same major version as the Spec that it implements in certain language. " |
@yurishkuro @bogdandrutu can you please discuss and come to a consensus on this one? I am OK with either approach (requiring or no requiring major version number to be the same). If you agree on what to do I will be happy to capture it in this PR. |
|
An unsolicited opinion:
|
Yes, this is already added as a requirement in this PR.
One argument in favour of aligning major version numbers is that it contains the decision that we are making now within current major version number (0.x). It requires that Spec, API and SDK all use 0 as major version number. If we remove this requirement we will allow to pollute version number space in a way that may not be reversible. If in the future we decide to change the decision that we are making now and have different rules for let's say version 1.x we may not be able to do it because we may have artifacts of Spec 0.x that are using version 1.x numbers (or even higher major version numbers).
This is achieved automatically if we accept the requirement to keep major version numbers aligned. |
|
I think between API and SDK we can keep consistency version. The argument here can be:
|
|
@bogdandrutu if API and SDK are kept in the same repo, then PRs can still work the same, without coupling the versions. As an example for decoupling versions, OpenTracing API for Python is v2.x, but Jaeger client implementing that API is v4.x - because the client (SDK) was evolving, changing its internal APIs, etc., so we had to release major versions to maintain the semver rules. |
|
Ok, I see your point @yurishkuro. Let's propose a compromise at least for v0.x, we release both packages in the same time API/SDK because we will most likely develop both in parallel and revisit this for >1.x? |
|
yes, I think it's fine to do for 0.x and even 1.x, fairly unlikely that the major versions would diverge very quickly (especially given that SDKs are essentially recreated from prior art, including lessons learned) |
|
But that would be just practical consequences, I would rather not enshrine |
specification/library-guidelines.md
Outdated
|
|
||
| This weak coupling of version numbers allows language library authors to make patch and minor version SDK releases independently without the need to coordinate and match version numbers with API specification. The requirement to use the same major version number is aimed to avoid spilling over SDK version numbers into next major version in case we decide to change this policy starting from certain major version in the future. | ||
|
|
||
| Because API and SDK version numbers are not strictly coupled every SDK release MUST clearly specify API version number that it implements. Language library authors MUST include this information in SDK release notes. For example the release notes may say: "SDK 0.3.4, implements API 0.1.0". |
There was a problem hiding this comment.
Also, please reference the version of the spec.
|
Thanks for driving this @tigrannajaryan. I share @yurishkuro's experiences from OpenTracing - too many practical difficulties presented themselves to keep the versions in sync at any level, even though we were interested in doing so. (I will point out that it could be possible to could keep the major version numbers the same, if we choose to not use semver for OpenTelemetry. But I'm not suggesting we do that.) On the plus side, while it would be nice and clean to have the versions relate, I do not think it will be an issue in practice. End users, for the most part, do not notice these details very frequently, as most package managers handle the dependency resolution for them. And, for the most part, end users are not cross-referencing the work they are doing with the spec. As long as we have a compatibility matrix posted in our documentation, and each SDK release references the API and spec it is built against, the users who need to cross-reference will be satisfied. |
|
@yurishkuro @bogdandrutu @tedsuo to summarize this is what we are converging on:
Is this correct? |
|
btw, would merging of https://github.com/open-telemetry/opentelemetry-specification/pull/115/files help to understand this PR as well? |
I beleive #115 depends on what we decide here. So this one should be resolved and merged first. |
## Problem Description We assume that API specification will have a version number. We also assume that SDK's will implement a particular API version. Library authors may want to make multiple SDK releases that are implementing a particular API version. For example, we may start with API version 1.0.0 and make an SDK release 1.0.0 that implements that particular API. Later library authors may want to make a bug fix in the SDK and release 1.0.1. Note that this release implements the same API version, there are no changes from API perspective. Now we are in a situation when API and SDK versions diverged. This diverging seems inevitable because most likely API versions will change much less frequently than library authors will want to make SDK releases that implement those particular API versions. ## Proposed Solution Both API and SDK will semantic version numbers. API and SDK version numbers will not be strictly coupled. SDK is free to have a separate version number with one limitation: major version number of the SDK must be the same as the major version number of the API that the SDK implements. For example SDKs 0.1.0, 0.2.3, 0.7.0 can all implement API 0.1.0, but SDK 1.0.0 cannot implement API 0.1.0. This weak coupling of version numbers allows language library authors to make patch and minor version SDK releases independently without the need to coordinate version numbers with API specification. The requirement to use the same major version number is aimed to minimize the element of surprise and avoid spilling SDK version numbers into next major version in case we decide the policy starting from certain major version in the future. Because API and SDK version numbers are not strictly coupled every SDK release must clearly specify API version number that it implements. Language library authors must include this information in SDK release notes. For example the release notes may say: "SDK 0.3.4, implements API 0.1.0". ## Alternate Solutions Two other solutions were considered but saw less support: 1. Complete decouple SDK and API version numbers. SDK can use any version, including a different version number. The downside of this solution is that it can create a situation when in the future if we decide version labeling policy it may be too late since there may exist SDKs versions that spill into the next major version. To keep our options open the major version number restriction was proposed. 2. Couple major and minor version numbers of SDK and API, only allow SDK to freely change patch version number and always use 0 patch number for API versions. The downside of this solution is that SDK releases can only make patch releases if they implement the same API or they have to break the semantic versioning rule and allow significant changes while only incrementing patch number. Implements open-telemetry#276 and open-telemetry#246
tigrannajaryan
force-pushed
the
feature/tigran/versionlabeling
branch
from
fc7d3da
to
720d327
Compare
|
#280 (comment) sgtm |
There was a problem hiding this comment.
@tigrannajaryan I agree with your summary. Leave an approval now with the assumption a final PR will add the agreed upon changes.
|
@bogdandrutu @tedsuo @yurishkuro I updated the text, please have a look. |
|
LGTM |
* Proposal: API and SDK version labeling ## Problem Description We assume that API specification will have a version number. We also assume that SDK's will implement a particular API version. Library authors may want to make multiple SDK releases that are implementing a particular API version. For example, we may start with API version 1.0.0 and make an SDK release 1.0.0 that implements that particular API. Later library authors may want to make a bug fix in the SDK and release 1.0.1. Note that this release implements the same API version, there are no changes from API perspective. Now we are in a situation when API and SDK versions diverged. This diverging seems inevitable because most likely API versions will change much less frequently than library authors will want to make SDK releases that implement those particular API versions. ## Proposed Solution Both API and SDK will semantic version numbers. API and SDK version numbers will not be strictly coupled. SDK is free to have a separate version number with one limitation: major version number of the SDK must be the same as the major version number of the API that the SDK implements. For example SDKs 0.1.0, 0.2.3, 0.7.0 can all implement API 0.1.0, but SDK 1.0.0 cannot implement API 0.1.0. This weak coupling of version numbers allows language library authors to make patch and minor version SDK releases independently without the need to coordinate version numbers with API specification. The requirement to use the same major version number is aimed to minimize the element of surprise and avoid spilling SDK version numbers into next major version in case we decide the policy starting from certain major version in the future. Because API and SDK version numbers are not strictly coupled every SDK release must clearly specify API version number that it implements. Language library authors must include this information in SDK release notes. For example the release notes may say: "SDK 0.3.4, implements API 0.1.0". ## Alternate Solutions Two other solutions were considered but saw less support: 1. Complete decouple SDK and API version numbers. SDK can use any version, including a different version number. The downside of this solution is that it can create a situation when in the future if we decide version labeling policy it may be too late since there may exist SDKs versions that spill into the next major version. To keep our options open the major version number restriction was proposed. 2. Couple major and minor version numbers of SDK and API, only allow SDK to freely change patch version number and always use 0 patch number for API versions. The downside of this solution is that SDK releases can only make patch releases if they implement the same API or they have to break the semantic versioning rule and allow significant changes while only incrementing patch number. Implements open-telemetry#276 and open-telemetry#246 * PR fixes
* Proposal: API and SDK version labeling ## Problem Description We assume that API specification will have a version number. We also assume that SDK's will implement a particular API version. Library authors may want to make multiple SDK releases that are implementing a particular API version. For example, we may start with API version 1.0.0 and make an SDK release 1.0.0 that implements that particular API. Later library authors may want to make a bug fix in the SDK and release 1.0.1. Note that this release implements the same API version, there are no changes from API perspective. Now we are in a situation when API and SDK versions diverged. This diverging seems inevitable because most likely API versions will change much less frequently than library authors will want to make SDK releases that implement those particular API versions. ## Proposed Solution Both API and SDK will semantic version numbers. API and SDK version numbers will not be strictly coupled. SDK is free to have a separate version number with one limitation: major version number of the SDK must be the same as the major version number of the API that the SDK implements. For example SDKs 0.1.0, 0.2.3, 0.7.0 can all implement API 0.1.0, but SDK 1.0.0 cannot implement API 0.1.0. This weak coupling of version numbers allows language library authors to make patch and minor version SDK releases independently without the need to coordinate version numbers with API specification. The requirement to use the same major version number is aimed to minimize the element of surprise and avoid spilling SDK version numbers into next major version in case we decide the policy starting from certain major version in the future. Because API and SDK version numbers are not strictly coupled every SDK release must clearly specify API version number that it implements. Language library authors must include this information in SDK release notes. For example the release notes may say: "SDK 0.3.4, implements API 0.1.0". ## Alternate Solutions Two other solutions were considered but saw less support: 1. Complete decouple SDK and API version numbers. SDK can use any version, including a different version number. The downside of this solution is that it can create a situation when in the future if we decide version labeling policy it may be too late since there may exist SDKs versions that spill into the next major version. To keep our options open the major version number restriction was proposed. 2. Couple major and minor version numbers of SDK and API, only allow SDK to freely change patch version number and always use 0 patch number for API versions. The downside of this solution is that SDK releases can only make patch releases if they implement the same API or they have to break the semantic versioning rule and allow significant changes while only incrementing patch number. Implements open-telemetry#276 and open-telemetry#246 * PR fixes
Problem Description
We assume that API specification will have a version number.
We also assume that SDK's will implement a particular API version.
Library authors may want to make multiple SDK releases that are
implementing a particular API version. For example, we may start
with API version 1.0.0 and make an SDK release 1.0.0 that
implements that particular API.
Later library authors may want to make a bug fix in the SDK and
release 1.0.1. Note that this release implements the same API
version, there are no changes from API perspective. Now we are in
a situation when API and SDK versions diverged.
This diverging seems inevitable because most likely API versions
will change much less frequently than library authors will want
to make SDK releases that implement those particular API versions.
Proposed Solution
Both API and SDK will use semantic version numbers. API and SDK
version numbers will not be coupled. API and SDK is free to have
separate version numberss
This decoupling of version numbers allows language library
authors to make patch and minor version API and SDK package releases
independently without the need to coordinate version numbers with
specification.
Alternate Solutions
Another solution was considered but saw less support:
Couple major and minor version numbers of SDK and API, only allow
SDK to freely change patch version number and always use 0 patch
number for API versions. The downside of this solution is that SDK
releases can only make patch releases if they implement the same
API or they have to break the semantic versioning rule and allow
significant changes while only incrementing patch number.
=======================
Implements #276 and #246