Add rationale document with versioning/releasing details

[lzchen]

Addresses: open-telemetry/opentelemetry-specification#1267
Fixes: #1458

[codeboten]

Some questions that come to mind:

• how are other packages versioned (proto/instrumentation/exporters)?
• how will code be marked as experimental?

[lzchen]

@codeboten

how are other packages versioned (proto/instrumentation/exporters)?

According to the otep, "Note that contrib packages are released separately from core packages. Contrib releases are not required to match version numbers with the core releases.". In terms of behaviour, look at "Contrib Stability" in the otep.
Open to suggestions on how to actually implement this.
In my opinion, we should do a similar release for contrib components like 1.0.0, which guarantees backwards compatibility for every change following it. Every change will result in a minor upgrade. As outlined in the otep, I don't believe we should upgrade versions across contribs for every release (currently, we bump all versions regardless if there are changes).
Thoughts?

how will code be marked as experimental?

Everything that exists in the in the X-experimental packages that are released are "experimental".
If you are asking about how we actually execute this in our codebase, we can probably create an "experimental" folder or use a different branch. However, these execution details do not need to be in this document.

[codeboten]

According to the otep, "Note that contrib packages are released separately from core packages. Contrib releases are not required to match version numbers with the core releases.". In terms of behaviour, look at "Contrib Stability" in the otep.
Open to suggestions on how to actually implement this.
In my opinion, we should do a similar release for contrib components like 1.0.0, which guarantees backwards compatibility for every change following it. Every change will result in a minor upgrade. As outlined in the otep, I don't believe we should upgrade versions across contribs for every release (currently, we bump all versions regardless if there are changes).
Thoughts?

Right, I guess my question was more specifically around packages that are part of this repo rather than the contrib repo. Or does contrib include things like the OTLP or jaeger exporter packages? I would expect the same release strategy should be used on all packages that are officially supported by opentelemetry, which in this case would include the packages in this repo.

I guess what I'm saying is that all things that we're creating packages for that are not well enough spec'd out should be marked as experimental. Does that make sense?

[lzchen]

@codeboten

Right, I guess my question was more specifically around packages that are part of this repo rather than the contrib repo.

"Contrib" in this document does not refer to the contrib repo. According to the otep:
Contrib: plugins and instrumentation that make use of the API or SDK interfaces, but are not part of the core packages necessary for running OTel.

So my understanding is that OTLP or jaeger exporter is part of this "Contrib" definition. I agree for following the same release strategy, however, I do not think we need to maintain versions in lockstep with the api and sdk.

I guess what I'm saying is that all things that we're creating packages for that are not well enough spec'd out should be marked as experimental. Does that make sense?

This makes sense. Anything with specs that are not stable should remain in experimental until the specs for them are stable.

[tedsuo]

For clarity, contrib does refer to the contrib repo. Everything in that repo must be kept up to date with the latest release in a timely fashion, but can have its own version number and be released separately.

Any plugin that lives in core must get versioned as part of the SDK. IMHO, that makes sense for OTLP and trace-context, but less sense for Prometheus, jaeger, etc.

I think this comes back to distros, and how we bundle up contrib plugins for release. I'm not interested in creating churn, but it does seem like we have contrib items living in core for reasons of convenience that were perhaps temporary.

[lzchen]

@tedsuo
What would be the action item for Prometheus, Jaeger, etc? Would these be moved to contrib?

[owais]

Must they always remain backward compatible? Could an SDK release a v2 or v3 that introduce breaking changes to SDK but still confirms to API 1.x? I know this shouldn't ideally happen but does the spec allow it?

[lzchen]

This is taken right from the specs. Spec enforces backwards compatibility between SDK versions. My understanding is that a breaking change requires a major version bump (from 1.X.Y -> 2.0.0).

[codeboten]

👍