Define version labeling schema for API and SDK #246
Assignees
Milestone
Comments
|
I can think of two other approaches:
|
|
@pavolloffay I don't think item 1 would work, because SDK may even need to release major versions if it's architecture changes significantly or some of its SPIs have breaking changes. Item 2 is an implementation detail of a two-versions strategy. To clarify Tigran's question, while two versions are a bit confusing, we haven't come up with a better approach so far. One alternative is to version API and SDK under the same version for any breaking changes, but it's a poor experience for the owners of instrumentation who should not really care about the SDK changes. And it makes the definition of N-1 compatibility quite ambiguous. I am still in favor of two versions approach, but it may need more explanation/education for the users. |
|
There is a related request asking to version the tracing and metrics APIs independently: open-telemetry/opentelemetry-go#111 It's a reasonable request, I think. It implies that we'd want to use a separate Github repository for each API and another repository for the SDK. Then the semver tagging of each will work independently. |
tigrannajaryan
pushed a commit
to tigrannajaryan/opentelemetry-specification
that referenced
this issue
Oct 1, 2019
## 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
|
See proposal here #280 |
tigrannajaryan
pushed a commit
to tigrannajaryan/opentelemetry-specification
that referenced
this issue
Oct 3, 2019
## 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
bogdandrutu
pushed a commit
that referenced
this issue
Oct 5, 2019
* 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 #276 and #246 * PR fixes
|
Closing this as #280 has merged. |
SergeyKanzhelev
pushed a commit
to SergeyKanzhelev/opentelemetry-specification
that referenced
this issue
Feb 18, 2020
* 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
TuckTuckFloof
pushed a commit
to TuckTuckFloof/opentelemetry-specification
that referenced
this issue
Oct 15, 2020
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
We need to have a well-defined schema for API and SDK versioning. The PR here #115 got stalled because I haven't yet been able to find a satisfactory approach to API and SDK version decoupling.
I am raising this issue to seek feedback and proposals.
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.
One possible solution is to declare that an SDK will be tagged by 2 version numbers:
These version numbers are decoupled and can be changed independently. So for example one may have an SDK 1.0.10 that implements API 1.0.0, or have SDK 1.5.10 that implements API 1.1.0.
However, I and @yurishkuro do not really like this approach, it is far from being elegant and is confusing.
Better suggestions are welcome.
The text was updated successfully, but these errors were encountered: