Closed lmolkova closed 5 months ago
I think the cleanest solution from user perspective would be option 2:
we'd have semantic-conventions-java:1.0.0
with stable only, semantic-conventions-java:1.0.0-beta.1
with all semconvs. Experimental -> stable transition requires no action on the user side.
It's also one of the common patterns to ship experimental features.
We can also discuss at the SIG meeting, but I always have a conflict discussing the same thing with Python SIG at the same time:)
Once we pick the ideal solution I'll make another pass on build-tools to add convenience for this specific case if anything else is necessary.
We discussed in the 3/14/24 Java SIG. Decided that a single artifact is probably not the right approach based on the following example:
libraryA
which depends on :semantic-conventions-java:1.0.0-beta
libraryB
which depends on :semantic-conventions-java:1.0.0
libraryC
which depends on :semantic-conventions-java:1.1.0
The normal way to resolve dependency version conflicts is to update to the latest of all dependencies. In this case, 1.1.0
. But doing so would expose the app to runtime errors since libraryA
was compiled against 1.0.0-beta
, which contains experimental attributes not available in 1.1.0
. To resolve, the app owner would have to intervene and set the version to 1.1.0-beta
.
The consensus of the discussion was to:
opentelemetry-semconv
and opentelemetry-semconv-incubating
(as merged to main currently)opentelemetry-semconv
only contains stable semantic conventions.
io.opentelemetry.semconv
package@deprecated
opentelemetry-semconv-incubating
contains stable and incubating semantic conventions
io.opentelemetry.semconv.incubating
package. Note this is different than stable artifact to make java module system work.@deprecated
with javadoc pointing to the equivalent location in the stable artifactsemantic-conventions
repo will keep incubating attributes around indefinitely (or for a long time) and mark as deprecated. These deprecated, experimental attributes will be annotated @deprecated
.alpha
, since we may eventually remove some deprecated experimental attributes, and since the types of experimental attributes are subject to change.Note that #45 is aligned with this strategy, except in that it does not currently retain deprecated experimental attributes. Will address that in a followup.
Extracted from #45
Repeating the question I left on the python PR https://github.com/open-telemetry/opentelemetry-python/pull/3586#issuecomment-1973978521
Option 1: ship 2 artifacts (
semconv
andsemconv-incubating
) - current solutionIt's aligned with semantic versioning, easy to maintain. Still having stable attributes as deprecated in the incubating artifact is not great.
Option 2: ship 1 artifact, but two different versions: stable and preview. Stable contains only stable semconv. Preview contains all of them.
Ideal in terms of semantic versioning. When attribute stabilizes, it remains in the same namespace and all libs/apps that depend on it don't need to change The only downside is that it could be harder to maintain and release.
Option 3: Probably not applicable to Java - ship 1 artifact, 1 version containing stable and experimental semconv. Emphasize that some parts are experimental via namespace (
import semconv.experimental.foo_attributes
, perhaps we should call it_experimental
)?It's easy to do, but violates semantic versioning. When attribute stabilizes, it moves to a different namespace, i.e. libs/apps that depend on it need to change.