Skip to content

Add new *.impl.* package convention, internal code with japicmp compatibility#8325

Merged
jack-berg merged 3 commits intoopen-telemetry:mainfrom
jack-berg:new-impl-code-convention
Apr 24, 2026
Merged

Add new *.impl.* package convention, internal code with japicmp compatibility#8325
jack-berg merged 3 commits intoopen-telemetry:mainfrom
jack-berg:new-impl-code-convention

Conversation

@jack-berg
Copy link
Copy Markdown
Member

Related to #6970.

We need a new stability tier for code that is public (for cross-module access within the OpenTelemetry project) but not intended for application developers — with full backwards-compatibility guarantees, unlike .internal..

As discussed in 4/23 java SIG, ApiUsageLogger from #8318 is an early candidate for this.

Others potential candidates:

  • CompoenntId and other internal instrumentation utils
  • ComponentRegistry and other internal SDK implementation utils (ThrottlingLogger, DaemonThreadfactory, GlobUtil, etc)
  • GrpcExporter, HttpExporter, and other exporter impelemtnation utils
  • And more

Options considered:

  • .util.: rejected because Java developers associate "util" with user-facing packages (java.util.concurrent, etc.), which may mislead application developers into thinking the code is for them.
  • .internal.shared. / .internal.stable.: rejected because these live under .internal., which the project has established as meaning unstable. Carving out a stable sub-package would contradict that convention and require fiddly japicmp exclusion changes.
  • .moduleinternal. / .componentapi.: considered but rejected as too verbose or without prior art in the Java ecosystem.
  • .impl.chosen because it is a reasonably well-understood Java idiom signaling "implementation detail, not user-facing API", it does not conflict with any existing OTel package conventions, and it falls outside the current japicmp exclusion patterns (*.internal / .internal.) so compatibility checking applies automatically with no build config changes.

Classes in .impl. packages must include standard javadoc boilerplate:

This class is not intended for use by application developers. Its API is stable and will not be changed or removed in a backwards-incompatible manner.

@codecov
Copy link
Copy Markdown

codecov Bot commented Apr 23, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.27%. Comparing base (fdb8194) to head (dec019e).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files
@@            Coverage Diff            @@
##               main    #8325   +/-   ##
=========================================
  Coverage     90.27%   90.27%           
  Complexity     7693     7693           
=========================================
  Files           850      850           
  Lines         23207    23207           
  Branches       2356     2356           
=========================================
  Hits          20951    20951           
  Misses         1530     1530           
  Partials        726      726           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Copy link
Copy Markdown
Member

@trask trask left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like .impl

I assume there's nothing worth adding to VERSIONING.md since it's just a normal stable class from that perspective?

Comment thread docs/knowledge/general-patterns.md Outdated
Co-authored-by: Jay DeLuca <jaydeluca4@gmail.com>
@jack-berg jack-berg merged commit 5b7a7f2 into open-telemetry:main Apr 24, 2026
28 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants