Document compatibility between modules

[pellared]

Documents https://github.com/open-telemetry/opentelemetry-go/issues/3548

[codecov[bot]]

Codecov Report

Merging #3806 (a04c8fb) into main (01bbea3) will increase coverage by 0.0%. The diff coverage is n/a.

Additional details and impacted files

@@          Coverage Diff          @@
##            main   #3806   +/-   ##
=====================================
  Coverage   81.6%   81.7%           
=====================================
  Files        167     167           
  Lines      12459   12462    +3     
=====================================
+ Hits       10179   10182    +3     
  Misses      2065    2065           
  Partials     215     215           

Impacted Files	Coverage Δ
exporters/jaeger/jaeger.go	90.3% <0.0%> (-0.9%)	:arrow_down:
sdk/metric/pipeline.go	90.6% <0.0%> (+<0.1%)	:arrow_up:
sdk/trace/batch_span_processor.go	81.1% <0.0%> (+0.8%)	:arrow_up:

[pellared]

What about managed duplication through code generation?

That is exactly what I propose here

We could address the problem e.g. by using "code generation" to "copy/paste" the common code that is shared between modules.

Having that said, I think we should document the current state before we address the issue.

[ericklaus-wf]

I think the situation is more complicated than described in this documentation update. It isn't the case that modules are only compatible at the same version (go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.11.1 is only compatible with go.opentelemetry.io/otel v1.11.1). Instead, modules are only guaranteed compatible at releases from the same commit, which may be different versions.

For example, go.opentelemetry.io/otel/exporters/otlp/[email protected] is compatible with go.opentelemetry.io/[email protected] but is not compatible with go.opentelemetry.io/[email protected]. The only way to discover compatible versions is to manually inspect each git tag, looking for tags at the same commit. That feels like a pretty onerous burden, but documenting it here will at least make it clearer to your integrators what they're signing up for.

[MadVikingGod]

@pellared I did a bit of work to identify which modules take dependencies on cross-module internal packages here.

[pellared]

Closing. I assigned https://github.com/open-telemetry/opentelemetry-go/issues/3548 to myself.

[pellared]

I think the situation is more complicated than described in this documentation update. It isn't the case that modules are only compatible at the same version (go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.11.1 is only compatible with go.opentelemetry.io/otel v1.11.1). Instead, modules are only guaranteed compatible at releases from the same commit, which may be different versions.

For example, go.opentelemetry.io/otel/exporters/otlp/[email protected] is compatible with go.opentelemetry.io/[email protected] but is not compatible with go.opentelemetry.io/[email protected]. The only way to discover compatible versions is to manually inspect each git tag, looking for tags at the same commit. That feels like a pretty onerous burden, but documenting it here will at least make it clearer to your integrators what they're signing up for.

Correct. https://github.com/open-telemetry/opentelemetry-go/pull/3806/commits/cf20bc3bbfc289b93478215f580306223fe99781 😉