Versioning and stability document

[lalitb]

The Versioning documentation for this repo as required for #436

reference:

open-telemetry/oteps#143
open-telemetry/opentelemetry-specification#1267

[codecov]

Codecov Report

Merging #437 (15875d7) into master (9b94160) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #437   +/-   ##
=======================================
  Coverage   94.20%   94.20%           
=======================================
  Files         182      182           
  Lines        7853     7853           
=======================================
  Hits         7398     7398           
  Misses        455      455           

[maxgolov]

It'd be best to clarify on the best practices and coding convention here, such as HAVE_ABC or HAVE_FEATURE_ABC alike.

[lalitb]

done. Please feel free to provide suggestion if it's still not complete.

[maxgolov]

I thought we were to provide two packages:

• opentelemetry-api - header only.
• opentelemetry-sdk - implementation.

Do we need to cover opentelemetry-contrib in this repository? It'd be problematic to consolidate, or decide what is to. be included in -contrib. Most likely it would end up being opentelemetry-${VendorA} ?

[lalitb]

Yes, I will change it accordingly. We do add version information in both api and sdk to differentiate their versions. But honestly I still don't understand the concept of separate packages yet from C++ prospective. If we talk about output of out release management, it would still be single source zip/tar file containing both api and sdk. Or are we talking about vcpkg packages here : )

[lalitb]

Done changes. And removed -contrib. I actually felt there should be way for user's of -contrib repo to know which version of -api/sdk they would need for their exporter to work correctly.

[maxgolov]

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::TracerProvider in 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 as v1_2::TracerProvider - to cover the cases where refactor may break the ABI.

[jsuereth]

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.

[lalitb]

There are two aspects of ABI stability as I understand:

1. sdk compiled 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.
2. Doing sdk code 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.

[maxgolov]

I assume we are either adding git tags on master or create release/v1.0.0 branch.

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:

• API headers (header-only?), plus
• SDK implementation combined

And we do not release separate packages per se? Practical example: if I install a package on Ubuntu, usually I have package - the runtime, and package-dev - headers and libraries, documentation, possibly source, etc..

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 opentelemetry

That'd be ideal experience.

OR

apt install opentelemetry
apt install opentelemetry-dev

That'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.

[lalitb]

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).

[maxgolov]

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.

[maxgolov]

..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 opentelemetry package v1.0.0 , and produce their own build of it as opentelemetry-sdk-vendor package v1.0.0 that contains their own proprietary exporter implementation. Correspondingly, it'd make sense to later on describe how a sample app would be instrumented with either vendor SDK package, and maybe even with two different vendor packages at the same time, if necessary, i.e. using TraceProvider from Vendor A and TraceProvider from Vendor B.

[lalitb]

@maxgolov Based on the recent comment here
open-telemetry/oteps#143 (comment)

Seems decision is moving towards having different versions of api and sdk, and ask for us to get aligned to this.

[jsuereth]

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:

• Would we allow, say, a version 2.0 of the SDK to still have the API namespace v1 with compatibility?
• Do we expect projects to take a dependency on just the API without the SDK in the C++ world?
• Do we want a unified notion of artifact naming + versioning for various ecosystems?
  vcpkg, deb, rpm, source, bazel.
  Does this mean we'd own each of these packaging scenarios?

[lalitb]

Would we allow, say, a version 2.0 of the SDK to still have the API namespace v1 with compatibility?

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.

Do we expect projects to take a dependency on just the API without the SDK in the C++ world?

The opentelemetry-api should be enough for instrumenting any library, with final choice of SDK deferred to application developer.

Do we want a unified notion of artifact naming + versioning for various ecosystems?

We don't plan to own all the ecosystems, the official release would be source(zip/tar) package(s):
Either single source package like
opentelemtry-1.0.0
or several:
opentelemetry-api-1.0.0, opentelemetry-sdk-1.0.1, opentelemetry-exporter-zipkin-1.0.1

[maxgolov]

It's generally Okay, but I think for the final build artifact / deliverable package, we should say that in our case we combine API+SDK, we keep both versions in line one with another, and we ship just opentelemetry metapackage that is a combination of api and sdk , where subsequently vendors may take that metapackage and build their own opentelemetry-sdk-${vendor} with custom vendor-provided exporters, like opentelemetry-sdk-azure or opentelemetry-sdk-aws or opentelemetry-sdk-gcp or alike, with a guarantee of ABI/API compatibility - should vendor decide to provide a prebuilt package for their flow.

[jsuereth]

I think this is a good first pass at stability and lines up with where I thought C++ was going to be.

Two points of discussion for SIG / follow on work:

• Do we want to split the API into its own versioning/artifact?
• How do we plan to do "incompatible" changes to API (e.g. will allow an extension mechanism).

Personally, I'd rather start operating as if everything we do is stable and ensure we have a clear path for opening up features (with -DFEATURE) and learn/use compatible techniques now. If we have to do it post GA, we might as well do it from our first release and have a hard discussion when we think we would have to break something.

[jsuereth]

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.

[jsuereth]

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:

• Would we allow, say, a version 2.0 of the SDK to still have the API namespace v1 with compatibility?
• Do we expect projects to take a dependency on just the API without the SDK in the C++ world?
• Do we want a unified notion of artifact naming + versioning for various ecosystems?
  vcpkg, deb, rpm, source, bazel.
  Does this mean we'd own each of these packaging scenarios?

[lalitb]

Thanks for the comments. I have updated the document for ABI stability, and indicating different packages for api and sdk. Will merge it , and will initiate ffurther discussions on separate github issue/discussion.

All suggested changes are done. So dismissing the review. Will open separate github issue forum for further discussion