Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/knowledge/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ is the signal.
|------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
| [build.md](build.md) | Always — build requirements and common tasks |
| [general-patterns.md](general-patterns.md) | Always — style, nullability, visibility, AutoValue, locking, logging, internal & impl packages |
| [api-design.md](api-design.md) | Public API additions, removals, renames, or deprecations or implementations; configuration changes; null guards; stable vs alpha compatibility |
| [api-design.md](api-design.md) | Public API additions, removals, renames, or deprecations or implementations; configuration changes; module layout; null guards; stable vs alpha compatibility |
| [gradle-conventions.md](gradle-conventions.md) | `build.gradle.kts` or `settings.gradle.kts` changes; new modules |
| [testing-patterns.md](testing-patterns.md) | Test files in scope — assertions, test utilities, test suites |
| [other-tasks.md](other-tasks.md) | Dev environment setup, benchmarks, composite builds, native image tests, OTLP protobuf updates |
Expand Down
10 changes: 10 additions & 0 deletions docs/knowledge/api-design.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,16 @@ Follow specification-defined semantics. Relaxing an API to accept a previously
rejected `0` is allowed, including in stable modules. Document and test zero
behavior explicitly.

## Dependency isolation

Make interactions with load-bearing dependencies pluggable via SPI, with implementations in separate modules. This lets
users replace toxic dependencies or accommodate version conflicts and library preferences. Examples include YAML parsing
and object conversion in declarative config, and HTTP transport in `exporters/sender/`. Include the dependency's name
and major version in implementation module names and base packages:
`opentelemetry-sdk-extension-declarative-config-jackson2` and
`io.opentelemetry.sdk.autoconfigure.declarativeconfig.jackson2` allow a Jackson 3 implementation to coexist later. See
[module naming](gradle-conventions.md#module-naming).

## Deprecating API

Applies to both stable and alpha modules. Use plain `@Deprecated` — do **not** use
Expand Down
4 changes: 4 additions & 0 deletions docs/knowledge/general-patterns.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,10 @@ Use [AutoValue](https://github.com/google/auto/tree/master/value) for new value
- Add a package-private constructor to all AutoValue classes to prevent external extension.
- `japicmp` allows new abstract methods on AutoValue classes — the `AllowNewAbstractMethodOnAutovalueClasses` rule handles this.

## Changelog

Do not add changelog entries to PRs. They are generated during the [release process](../../RELEASING.md).

## Class member ordering

In general, order class members as follows:
Expand Down
5 changes: 5 additions & 0 deletions docs/knowledge/gradle-conventions.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,11 @@ When the archive name cannot be derived correctly from the project name, set it
base.archivesName.set("opentelemetry-api")
```

SPI implementation module names and base packages should include the key dependency's name and major version. For
example, `opentelemetry-sdk-extension-declarative-config-jackson2` uses
`io.opentelemetry.sdk.autoconfigure.declarativeconfig.jackson2`. This allows a `declarative-config-jackson3`
implementation to coexist later. See [dependency isolation](api-design.md#dependency-isolation).

## `settings.gradle.kts` ordering

New `include(...)` entries must be in **alphabetical order** within their surrounding group. The
Expand Down
Loading