Strengthen versioning requirements #6970
Labels
Comments
This was referenced Dec 19, 2024
|
#6978 adds a new architecture check to Some common threads (but not an exhaustive analysis): Initialize autovalue {Signal}Data implementationsImplementation / usage of experimental codeExtendedTextMapGetterDeclarative config's StructuredConfigProperties, ComponentProviderScopeConfiguratorCompressorExporter common utilitiesMarshalerExporterMetricssuppressInstrumentationInternal utility classes that could be publicApiUsageLoggerThrottlingLoggerDynamicPrimitiveLongListcheckArgumentStringUtils isNullOrEmpty, paddLeftDaemonThreadFactoryAttributesMapComponentRegistryWeakConcurrentMap |
|
@jack-berg can I please work on this? |
This is a sort of a overall tracking issue which if we agree on a path forward, will likely have many contributing PRs over a long time. In today's 1/9 java SIG, we discussed this. Some notes:
I'd say if you want to help, take a look at reviewing #6944 and #6978 for now. After than, we can work out strategies for beginning to tackle the large task of removing shared internal code. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
We do two things that are problematic for consumers:
1. Stable artifacts can take
implementationdependencies on experimental artifactsAs 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
-alphaartifacts 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
compileOnlydependencies on experimental artifacts.compileOnlydependencies don't show up in the published*.pomfile or./gradlew dependenciesof 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-apiwhere the class resides, such as DebugConfig inopentelemetry-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
ConfigUtilmakes an allowed breaking change to its API and the versions ofopentelemetry-apiandopentelemetry-sdk-metricsare not aligned, thenDebugConfigis 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:
The result would be that every artifact is complete self contained, except for calls to public API from transitive dependencies.
The text was updated successfully, but these errors were encountered: