Release note not including the spec version

[Emily-Jiang]

I found it difficult to track down the spec version aligned in each individual release. I think we discussed this in the past and agreed to add the spec version in the release not, but I could not see the implementation. Is it possible to list the spec version somewhere for each release?

[jack-berg]

I assume you're referring to the version of the specification used in semantic conventions? The semantic convention repository recently was split out from the opentelemetry-specification repository to allow semantic conventions to be versioned independently from the specification.

Its not clear what the release cadence will be for the semantic-conventions repo, but I think the next release won't be until they are ready to mark the http semantic conventions as stable. That would be a good point in time to split out opentelemetry-semconv from this repo. When we do that, the problem of clarifying the version of semantic conventions in opentelemetry-java will have gone away.

[Emily-Jiang]

I am referring to OpenTelemetry spec. I think right now it is based on 1.19 not 1.20. However, it is difficult to work out which spec version one particular otel-java release is based on.

[jack-berg]

Hm...

No version of opentelemetry-java is perfectly aligned with the specification. The specification is a moving target and a particular version of opentelemetry-java will never have features which exceed the latest specification version available at the time of publication. But that doesn't mean that opentelemetry-java will contain all the latest features of the latest specification version.

So including the latest specification version in opentelemetry-java only really says "this version of opentelemetry-java does not contain specification features that were introduced after specification version x".

Is that really valuable?

[brunobat]

I find that most problems (breaking changes) happen in changes with the instrumentation-api, not in the opentelemetry-java project.
The lack of awareness on spec. features that are effectively implemented can be addressed in a few ways, in my opinion:

1. Downstream projects can lock into a particular OTel java release version, document and support it while they use it.
2. Create the concept of an LTS release, on the OTel side, for opentelemetry-java and opentelemetry-java-instrumentation with extra polishing, detailed documentation and potencial backports. These LTS versions could them be used by stable downstream projects.
3. Something in between.

[mateuszrzeszutek]

instrumentation-api is a stable artifact; it is instrumentation-api-semconv that is unstable. Note that we're currently working on stabilizing the HTTP & network related utilities from the semconv module; come October these'll be included in the instrumentation-api module and subject to our usual stability guarantees for stable components.

[jack-berg]

Resolved by #5786.