Strengthen versioning requirements

[jack-berg]

We do two things that are problematic for consumers:

1. Stable artifacts can take implementation dependencies on experimental artifacts

As documented here. We don't let classes from the experimental artifacts enter the public API surface area. And by keeping it an implementation dependency, we require that consumers explicitly add their own dependency on the experimental artifact in order to use the experimental features.

This logic checks out to me, but there's still a perception problem when you've only included stable artifacts, yet see -alpha artifacts when you run ./gradlew dependencies.

Luckily, we've come a long way and there are very few experimental artifacts left. The ones that do exist are almost all "experimental by design" and will never change.

With a few changes, we can strengthen this guarantee and only allow stable artifacts to have compileOnly dependencies on experimental artifacts. compileOnly dependencies don't show up in the published *.pom file or ./gradlew dependencies of projects that depend on stable artifacts.

#6944 shows how we can accomplish this. I think we ought to take it a step further and add build tooling to verify we're following this guidance, just to prevent slip ups.

2. Various artifacts make use of shared internal code

For example, consider ConfigUtil which is used by various parts of the project outside the opentelemetry-api where the class resides, such as DebugConfig in opentelemetry-sdk-metrics.

This forces our users to make sure that versions of all artifacts are aligned, for which we recommended using a BOM. If versions aren't align, users could encounter a runtime error. For example, if ConfigUtil makes an allowed breaking change to its API and the versions of opentelemetry-api and opentelemetry-sdk-metrics are not aligned, then DebugConfig is prone to calling an API that doesn't exist.

Problem is, BOMs aren't bulletproof - there are other factors that influence the resolved dependency version, as we've seen numerous times the spring dependency management plugin.

Ideally, our artifacts should be resilient enough to work even when versions minor versions are not aligned.

I believe we can accomplish this if we ban use of shared internal code. If a particular artifact needs internal code from another, we can either:

• Consider promoting that to publish API surface area where it gets strong compatibility guarantees
• Make a copy of that code in the other artifact

The result would be that every artifact is complete self contained, except for calls to public API from transitive dependencies.