Releasing Packages in Contrib as 1.0 Stable

[NathanielRN]

Description

This issue came out as a result of the 2021-07-15 SIG Meeting Discussion.

Many other languages are already going to 1.0 for their contrib packages. See:

• Java Contrib at 1.0-alpha
• .NET Contrib at 1.0-preview
• Go CORE is at RC-1.0
• JavaScript CORE (and contrib?) is targeting 1.0 for end of August 2021

We also want to pave the way for individual contrib packages to be released as 1.0 for Python. This will allow companies/users to take dependencies on the useful packages in the contrib repository.

Reasons we are ready to go to 1.0:

• Semantic Conventions is already at version 1.5.0
  • Trace APIs are stable, only attributes are still experimental
  • For minor changes, they are providing schema files as a migration guide that SDKs/backends can use to find attributes as they change value/key.
• Our contrib packages already pin the version of opentelemetry-semantic-conventions they use which will allow them to move at their own pace (Go SDK does this)

Remaining Issues

In order to release packages in opentelemetry-python-contrib as 1.0 and therefore "stable", we want the following issues to be resolved:

• https://github.com/open-telemetry/opentelemetry-python-contrib/issues/550
• https://github.com/open-telemetry/opentelemetry-python-contrib/issues/589
• https://github.com/open-telemetry/opentelemetry-python-contrib/issues/590

Nice to Have Issues

• CODEOWNERS of packages can release (not merge updates) packages independent of maintainers (e.g. using GitHub Actions & Tags?)

[cijothomas]

Is this about releasing contrib packages as 1.0.0 or 1.0.0-preview? Since the semantic conventions are not declared stable, we cannot really do 1.0.0 on any packages which depends on them right? Almost all the instrumentation library do depend on semantic conventions, so they cannot be 1.0.0, but can be 1.0.0-preview.

[NathanielRN]

@cijothomas

Since the semantic conventions are not declared stable, we cannot really do 1.0.0 on any packages which depends on them right?

Although they are not stable, as I mentioned in the Issue Description above, they have defined schema files to help with migrations between versions. They are already at 1.5.0 because as far as I understand, through these schemas methods and others they will provide ways to be compatible between the versions for client/backend users alike. In that case this is about releasing contrib packages as 1.0.0.

[aabmass]

I have thought a bit more about this since the SIG.

They are already at 1.5.0 because as far as I understand, through these schemas methods and others they will provide ways to be compatible between the versions for client/backend users alike

I'm not entirely sure if the semantic conventions are "at" 1.5.0, that's just the current spec version right? Metrics is in the spec but also marked experimental. Being experimental, they are not guaranteed to be compatible from a code perspective. If the constant keys are changed, as was the case in https://github.com/open-telemetry/opentelemetry-python/pull/1946, we need to do a major version bump of the opentelemetry-semantic-conventions library. That would mean updating all of the instrumentations as well.

There are also issues like https://github.com/open-telemetry/opentelemetry-specification/issues/1747 that would make us change our instrumentations and need a major version bump for the instrumentation package.

• Our contrib packages already pin the version of opentelemetry-semantic-conventions they use which will allow them to move at their own pace (Go SDK does this)

I don't think we can pin these going forward, because it make instrumentations moving at their own pace incompatible with each other. E.g. if flask and postgres instrumentations depend on different versions of opentelemetry-semantic-conventions, it will be impossible to install those two instrumentations together (as they are pinned).