Versioning and Stability for OpenTelemetry Clients

[tedsuo]

Link to readable version: https://github.com/tedsuo/rfcs/blob/versioning/text/0143-versioning-and-stability.md

Versioning is a high priority as we still hope to get some kind of release or announcement out by end of year. This proposal explains the versioning protocol and stability guarantees for OpenTelemetry implementations in every language.

It would be a helpful exercise to have maintainers review this proposal, and write out their language specific-expectations.

Request for Maintainers: Please create a language-specific document which describes how versioning and support works for your language, based on this OTEP, and post a link to it in the tracking issue here. We want to ensure that versioning and support as been thought through before it is added to the spec.

Cheers,
-T

[tigrannajaryan]

I may have missed it but it is not clear to me if the OTEP requires that once 1.0 is released all releases that come after that must use 1.x or we still allow 0.x to be released after 1.0? Specifically, once we release 1.0 containing trace implementation do we continue working on metrics and releasing it as 0.x?

[tedsuo]

@tigrannajaryan the proposal is that opentelemtry-core should be considered a single code base and given a single version number. Changes to any portion version the entire codebase, according to the rules listed here.

[anuraaga]

Thanks!

[jsuereth]

Approving with caveat:

I think the notion of metric stability needs more discussion work. Sorry I was unavailable this week for community discussions. Don't want to hold up the progress this doc makes, but I do want to discuss if we need a stricter stability guarantee later. You can see my hastily written comments which hopefully demonstrate the issue. As this is only about stricter guarantees, I think it's safe to discuss this post adoption of minimum guarantees.

Thanks for putting this together @tedsuo!

[tedsuo]

Thanks @jsuereth I appreciate all of the input. Data stability will be a tricky wicket. Honestly, embedding metrics of any kind in standard instrumentation packages makes for difficult decisions. With tracing, events are simply reported as they happen, which is fairly objective once you have decided on the semantics. With metrics, decisions about what deserves to counted and how those counts should be factored are more fundamentally subjective. You can look at the consternation caused by the one major subjective decision in tracing – what qualifies as an error – and see the amount of debate that will be coming our way with metrics. This will surely spill over into stability issues and over-instrumentation unless we are able to develop a mental framework for guiding our decisions on this front.

Anyways, this will be our challenge for the new year! I look forwards to digging in after the holidays. Thank you for your interim approval; I'm now moving on to writing the spec PR. :)

[tigrannajaryan]

This has sufficient number of approvals. Given how important this is let's give everyone one more day to object and merge tomorrow.

[mtwo]

@tedsuo thanks for putting this together, seriously!

[arminru]

Thank you, Ted!

[tigrannajaryan]

@tedsuo can you please resolve any remaining open comments? I am not sure if there is anything that still needs to be addressed. I will merge once you confirm nothing remains that requires changes to the PR.

[tedsuo]

@tigrannajaryan I've resolved them, thank you. @yurishkuro if you have further questions do you mind moving them to the spec PR?

[tigrannajaryan]

Merging. Any further refinements can happen when this OTEP is merged to the spec. Thanks @tedsuo for this important OTEP.

[tedsuo]

Awesome, thank you @tigrannajaryan. And thank you everyone for all of the timely input!