Decide artifact name and versioning scheme

[jack-berg]

The existing semconv artifact is published under coordinates io.opentelemetry:opentelemetry-semconv:{version}, with the latest version being 1.29.0-alpha.

One of the primary reasons for creating a new semantic-conventions-java repo is so that it can version in lockstep with open-telemetry/semantic-conventions, whose latest release is v1.21.0.

If we use the same artifact coordinates and publish version in lockstep with the semantic-conventions repo, we'll have a conflict. I.e. when we publish a version corresponding to the next version of semantic-conventions v1.22.0, we'll have io.opentelemetry:opentelemetry-semconv:1.22.0-alpha, which already exists.

We should consider publishing under a new set of artifact coordinates. Perhaps we modify the group to be io.opentelemetry.semconv. This would align with other otel java repos and and allow us to avoid the conflict.

There's also the question discussed here. Should we create a versioning strategy to allow us to change the code generation logic independently of a new version of semantic conventions?

One way to do this would be to have versions of the form {CODE_GEN_VERSION}_{SEMCONV_VERSION}. E.g. 1.0.0_1.21.0, or perhaps more simply 1_1.21.0.

[jack-berg]

Option 1: Single version synchronized with semantic-conventions releases, i.e. v1.21.0. Encode code gen version in package name io.opentelemetry.semconv.v1_0.*.

• Pro: Simple, flexible for
• Con: If we change code gen logic, we'll need to continue publishing old generated code package forever, since we have no way to indicate breaking change in the artifact version.

Option 2: Multiple versions, each following semconv, i.e. v1.0.0_1.21.0

• Con: confusing and unfamiliar to users
• Con: Probably overkill. Since this repo doesn't depend on anything besides opentelemetry-api (for AttributeKey<?>), we shouldn't ever need to patch for security vulnerabilities. Any additional attributes we'd want to publish would have a corresponding version of semantic-conventions, so probably no need for minor.
• Pro: Preserves the ability to make major (breaking), minor, and patch changes to code gen logic if we ever find the need

Option 3: Multiple versions, with simplified code gen version, i.e. v1.0_1.21.0

• Con: confusing and unfamiliar to users. Not obvious why two versions and why one doesn't follow semantic versioning.
• Pro: Preserves the ability to make major (and possibly) minor changes to code gen logic.

Any other options?

My preference is for Option 1.

[jack-berg]

We talked about this in the 8/17/2023 Java SIG.

Conclusions:

• We want to go with the artifact coordinates as suggested: io.opentelemetry:opentelemetry-semconv
• We want to keep artifact version scheme simple and in lockstep with the semantic-conventions repo, e.g. v1.21.0 for the latest release.
  • If we publish a stable artifact and want to make breaking changes to the code generation logic, we can create a new package with the new version scheme. For example, if the initial release includes io.opentelemetry.semconv.v1.SemanticAttributes, we can make breaking in a new package / class: io.opentelemetry.semconv.v2.SemanticAttributes.
  • If we somehow botch the release and need to patch outside the semantic-conventions repo cycle, we can publish patch with a 4th element in the semantic versioning tag, e.g. v1.21.0.1 for the latest release. We'll only include the 4th element in the tag for patch releases as needed.

[jack-berg]

Resolved in #13.