Versioning and stability document #437
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,83 @@ | ||
| # Versioning | ||
|
|
||
| This document describes the versioning policy for this repository. | ||
|
|
||
| ## Goals | ||
|
|
||
| ### API Stability | ||
|
|
||
| Once the API for a given signal (spans, logs, metrics, baggage) has been officially released, that API module will function with any SDK that has the same MAJOR version and equal or greater MINOR or PATCH version. For example, application compiled with API v1.1 is compatible with SDK v1.1.2, v1.2.0, etc. | ||
|
|
||
| For example, libraries that are instrumented with `opentelemetry 1.0.1` will | ||
| function in applications using `opentelemetry 1.11.33` or `opentelemetry | ||
| 1.3.4`. | ||
|
|
||
| ### SDK Stability | ||
|
|
||
| Public portions of the SDK (constructors, configuration, end-user interfaces) | ||
| must remain backwards compatible. Internal types are allowed to break. | ||
|
|
||
| ## Policy | ||
|
|
||
| * Release versions will follow [SemVer 2.0](https://semver.org/). | ||
| * Only single source package containing api and sdk for all signals would be released as part of the new GitHub release. | ||
| * Experimental releases: New (unstable) telemetry signals and features will be introduced behind feature flag using C macro define. | ||
| ``` | ||
| #ifdef FEATURE_FLAG | ||
| <metrics api/sdk definitions> | ||
| #endif | ||
| ``` | ||
|
|
||
| As we deliver package in source form, and the user is responsible to build them for their platform, they must be | ||
| aware of these feature flags (documented in CHANGELOG.md), and enable it explicitly through their build system (cmake | ||
| , bazel or others ) to use the preview feature. | ||
|
|
||
| The guidelines in creating feature flag would be: | ||
| - Naming: | ||
|
|
||
| - `ENABLE_<SIGNAL>_PREVIEW` : For experimetal release of signal api/sdks eg, METRICS_PREVIEW, LOGGING_PREVIEW, | ||
|
|
||
| - `ENABLE_<SIGNAL>_<FEATURE_NAME>_PREVIEW` : For experimental release for any feature within stable signal. Eg, TRACING_JAEGER_PREVIEW to release the experimental Jaeger exporter for tracing. | ||
|
|
||
| - Cleanup: It is good practice to keep feature-flags shortlived as possible. And, aslo important to keep the number of them low. They should be used such that it is easy to remove/cleanup them once the experimental feature is stable. | ||
|
|
||
|
|
||
| * New signals will be stabilized via a **minor version bump**, and are not allowed to break existing stable interfaces. | ||
| Feature flag would be removed once we have a stable implementation for the signal. | ||
|
|
||
| * GitHub releases will be made for all released versions. | ||
|
|
||
| ## Example Versioning Lifecycle | ||
|
|
||
| Purely for illustration purposes, not intended to represent actual releases: | ||
|
There was a problem hiding this comment. I assume we are either adding git tags on For API+SDK in this repo, should we assume that we attempt to keep both API+SDK in sync at all times? For release packaging: assuming we use either CMake (git+tag) or vcpkg or bazel, isn't our mainline release always produces just one artifact, that is:
And we do not release separate packages per se? Practical example: if I install a package on Ubuntu, usually I have I understand the merit of logically splitting API vs. SDK, so that a vendor can implement their own SDK and exporters based on ABI-stable API. But from end-user consumption perspective, what are the release packages that we actually deliver and install? Example: vcpkg install opentelemetryThat'd be ideal experience. OR apt install opentelemetry
apt install opentelemetry-devThat's how I would've done the runtime vs. lib+headers+src+doc 'developer` package. Best how we can accommodate the API+SDK is to combine them into one ship'able artifact, i.e. one source tarball with given version v1.0.0. What are your own thoughts on that? i.e. irrespective of what OTEP is suggesting. There was a problem hiding this comment. My thoughts are also on similar lines. Ensuring that the API + SDK are sync all the time, and deliver one source package with both api + sdk as single version. Even if we want to package it through some package manager, let it be single package containing both headers (api) and lib (sdk). There was a problem hiding this comment. Yes, I think OTEP says should and may, and under the may - it recommends producing one package. It would be easier for us if we always enforce one common tag, common baseline, for api + sdk. Every time we change something either in API or in SDK, we update the tag, so the next release bumps-up both at the same time. There was a problem hiding this comment. ..for C++, I believe, the bigger challenge is that since we do not provide ABI stability guarantee for exporters -- it means vendors must build their own entire SDK with their custom exporter. Maybe we need to do the write-up later on how vendors take the There was a problem hiding this comment. @maxgolov Based on the recent comment here Seems decision is moving towards having different versions of api and sdk, and ask for us to get aligned to this. There was a problem hiding this comment. I think the idea there is the API is less-able-to-change than the SDK. Also, there's the notion that someone could take a dependency on the API itself without the SDK. For C++, a few guiding questions:
There was a problem hiding this comment.
As per what we plan to follow, API module will function with any SDK that has the same MAJOR version and equal or greater MINOR or PATCH version. As per otps, there is not going to be any 2.0 release for API and SDK.
The
We don't plan to own all the ecosystems, the official release would be source(zip/tar) package(s): |
||
|
|
||
| - v0.0.1 release: | ||
| - `opentelemetry-api 0.0.1` | ||
| - Contains experimental api's of trace, resouce ( no feature flag as major version is 0 ) | ||
| - No api's of logging and metrics available | ||
| - `opentelemetry-sdk 0.0.1` | ||
| - Contains experimental implementation of trace, resouce ( no feature flag as major version is 0 ) | ||
| - No implemtation of logging and metrics available | ||
| - v1.0.0 release: ( with traces ) | ||
| - `opentelemetry-api 1.0.0` | ||
| - Contains stable apis of trace, baggage and resource | ||
| - experimental metrics api's behind feature flag | ||
| - `opentelemetry-sdk 1.0.0` | ||
| - Contains stable implementation of trace, baggage and resource | ||
| - experimental metrics api's behind feature flag | ||
| - v1.5.0 release (with metrics) | ||
| - `opentelemetry-api 1.5.0` | ||
| - Contains stable api's of metrics, trace, baggage, resource, context modules | ||
| - experimental logging api still only behind feature flag | ||
| - `opentelemetry-sdk 1.5.0` | ||
| - Contains stable implementation of metrics, trace, baggage, resource, context modules | ||
| - experimental logging implementation still only behind feature flag | ||
| - v1.10.0 release (with logging) | ||
| - `opentelemetry-api 1.10.0` | ||
| - Contains stable api's of logging, metrics, trace, baggage, resource, context modules | ||
| - `opentelemetry-sdk 1.10.0` | ||
| - Contains stable sdk of logging, metrics, trace, baggage, resource, context modules | ||
|
|
||
| ### Before moving to version 1.0.0: | ||
|
|
||
| - Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable. | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we will run into problems when we add new methods or members to C++ class. It is inevitable that we'd end up doing some refactor for v1.x. Very bold, impractical and unrealistic expectation that we may freeze v1 in time and guarantee C++ API/ABI stability. While it may be easy to implement for other languages, we would have to be really creative and create some sort of enforcement via ABI compliance checker , OR allow for some additional flexibility. Such as, allowing
ot::v150::TracerProvider,ot::v151::TracerProviderin cases where we don't want to bump-up the MAJOR version. I read in the OTEP that it will take time to get to v2.. But that'll significantly constrain our abilities to address our customer feature needs --- given when we add new things, the newer version of the class may be breaking compatibility with old version. Once we release v1, we may need to have provision for inline namespaces such as v1_1, v1_2, etc. - where prebuilt SDK includes both, the original v1 class e.g.v1::TracerProvider, as well asv1_2::TracerProvider- to cover the cases where refactor may break the ABI.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The API already has version namespacing built-in: https://github.com/open-telemetry/opentelemetry-cpp/blob/master/api/include/opentelemetry/version.h#L11, so why not just have an OT_v1::ext:: thing?
However, the notion of "extension" isn't clear here. I agree with you we'd have to be creative if we find breaking changes in what we need to provide. I personally think stability guarantees are more improtant than flexibility on our end, but it would be good to brainstorm and have a plan for how we can address changes in compatible ways.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There are two aspects of ABI stability as I understand:
sdkcompiled against one version of C++ standard library should work with application/library compiled against different compiler/or different version same compiler. We don't guarantee that for our SDK ( though we do it for API ). And as we are going to release source packages, the vendor's compiling and using this sdk need to ensure this compatibility if they want so.sdkcode changes which are not backward ABI compatible - this is what we are discussing here. Going through this document - https://community.kde.org/Policies/Binary_Compatibility_Issues_With_C++ - It seems there are quite a few DON'T's to ensure the ABI stability. Would be good to go through them once and see if this is something doable once we reach first stable version v1.0. . If it is too large an ask, we do need to resort to namespace level versioning which will bring lots of overhead and noise in code to maintain different version internally.