Semantic versions for milestones #276
Assignees
Milestone
Comments
|
One problem with this table that it ignore language-specific conventions for version numbers. For example, python has special semantics for pre-release versions. We were planning to release python as |
I wonder the same thing. If we're following major/minor/patch semantics, I'd assume that either package could get a patch update without affecting the other. Major and minor updates to the API would require a major or minor update to the SDK (or the SDK would need to depend on an old version of the API), but not vice-versa. Another question is whether we're trying to keep the version of the clients in sync with the spec version. https://github.com/open-telemetry/opentelemetry-specification/blob/master/milestones.md#milestones seems to assume that we will, but that would mean that we can't release new major versions of clients without a corresponding major spec version change. |
|
I haven't reviewed the other proposals in a while (looking now), but a quick two cents to get python unstuck: High level description of our versioning (proposed)
|
|
Thanks @tedsuo.
I think we're going to run into a problem similar to #246 here. Where #246 describes the relationship between the SDK and API spec version, here the problem is between the API package version and API spec version. Following this would mean that we couldn't release major/minor updates to API packages without a corresponding spec change. I'll comment on #246 in detail.
For now we can release as
I agree, it sounds like we're ultimately going to call this |
|
Second @c24t that although it's great to align these things, it comes with the cost of not being idiomatic. In .NET a alpha/beta/preview package would have something append to the version, i.e: Preview: I wouldn't be surprised if tools check if id matches something like |
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
6 tasks
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
|
This issue was resolved in #280 |
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
For the defined milestones, the semantic version of library release is not mentioned. I think we should add version numbers to make things consistent across the languages.
For example,
0.2.00.2.10.2.20.2.n0.3.00.3.10.3.20.3.n0.4.00.4.10.4.20.4.n0.5.00.5.10.5.20.5.n1.0.01.0.11.0.21.0.nAlso, are we planning to keep API and SDK on the same versions? What if I changed (patch) the SDK, but not API? Should we still release API package with a new version?
Any thoughts?
The text was updated successfully, but these errors were encountered: