open-telemetry
/
opentelemetry-java
mirror of https://github.com/open-telemetry/opentelemetry-java.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Another option for release versioning proposal (#2250) 

* Add rationale and description of the release and versioning strategy.

* typo fix

* alternate version of the versioning strategy that tags the version rather than the artifact.

* add context for clarity

* Update docs/rationale.md

Co-authored-by: Nikita Salnikov-Tarnovski <gnikem@gmail.com>

* add some additional flavor about internals and mention the bom in an example

Co-authored-by: Nikita Salnikov-Tarnovski <gnikem@gmail.com>
This commit is contained in:
John Watson 2020-12-15 14:12:59 -08:00 committed by GitHub
parent 37afb33659
commit eccbfebf38
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 70 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
docs/rationale.md
View File

@ -23,4 +23,73 @@ try (Scope scope = TracingContextUtils.currentContextWith(span)) {
```
It would not be possible to call `recordException` if `span` was also using try-with-resources.
Because this is a common usage for spans, we do not support try-with-resources.
Because this is a common usage for spans, we do not support try-with-resources.
## Versioning and Releases
### Assumptions
- This project uses semver v2, as does the rest of OpenTelemetry.
### Goals
- API Stability:
- Once the API for a given signal (spans, logs, metrics, baggage) has been officially released, code instrumented with that API module will
function, *with no recompilation required*, with any API+SDK that has the same major version, and equal or greater minor or patch version.
- For example, libraries that are instrumented with `opentelemetry-api-trace:1.0.1` will function, at runtime with
SDK library `opentelemetry-sdk-trace:1.11.33` plus `opentelemetry-api-trace:1.11.33` (or whatever specific versions are specified by
the bom version `1.11.33`, if the individual versions have diverged).
- We call this requirement the "ABI" compatibility requirement for "Application Binary Interface" compatibility.
- SDK Stability:
- Public portions of the SDK (constructors, configuration, end-user interfaces) must remain backwards compatible.
- Precisely what this includes has yet to be delineated.
- Internal implementation details of both the API and SDK are allowed to be changed,
as long as the public APIs are not changed in an ABI-incompatible manner.
### Methods
- Mature signals
- API modules for mature (i.e. released) signals will be transitive dependencies of the `opentelemetry-api` module.
- Methods for accessing mature APIs will be added, as appropriate to the `OpenTelemetry` interface.
- SDK modules for mature (i.e. released) signals will be transitive dependencies of the `opentelemetry-sdk` module.
- Configuration options for the SDK modules for mature signals will be exposed, as appropriate, on the `OpenTelemetrySdk` class.
- Modules for these mature signals will be included in the opentelemetry-bom to ensure that users runtime dependencies are kept in sync.
- Mixing and matching runtime API and SDK versions, eg. by avoiding use of the BOM, will not be supported by this project.
- Once a public API (either in the official API or in the SDK) has been released, we will endeavor to support that API in perpetuity.
- Immature or experimental signals
- API modules for immature signals will not be transitive dependencies of the `opentelemetry-api` module.
- API modules will be versioned with an "-alpha" suffix to make it abundantly clear that depending on them is at your own risk.
- API modules for immature signals will be co-versioned along with mature API modules, with the added suffix.
- The java packages for immature APIs will be used as if they were mature signals. This will enable users to easily transition from immature to
mature usage, without having to change imports.
- SDK modules for immature signals will also be versioned with an "-alpha" suffix, in parallel to their API modules.
### Examples
Purely for illustration purposes, not intended to represent actual releases:
- `v1.0.0` release:
- `io.opentelemetry:opentelemetry-api:1.0.0`
- Includes APIs for tracing, baggage, context, propagators (via the context dependency)
- `io.opentelemetry:opentelemetry-api-metrics:1.0.0-alpha`
- Note: packages here are the final package structure: `io.opentelemetry.api.metrics.*`
- `io.opentelemetry:opentelemetry-sdk-trace:1.0.0`
- `io.opentelemetry:opentelemetry-sdk-common:1.0.0`
- Shared code for metrics/trace implementations (clocks, etc)
- `io.opentelemetry:opentelemetry-sdk-metrics:1.0.0-alpha`
- Note: packages here are the final package structure: `io.opentelemetry.sdk.metrics.*`
- `io.opentelemetry:opentelemetry-sdk-all:1.0.0`
- The SDK side of `io.opentelemetry:opentelemetry-api:1.0.0`
- No mention of metrics in here!
- `v1.15.0` release (with metrics)
- `io.opentelemetry:opentelemetry-api:1.15.0`
- Contains APIs for tracing, baggage, propagators (via the context dependency), metrics
- `io.opentelemetry:opentelemetry-sdk-trace:1.15.0`
- `io.opentelemetry:opentelemetry-sdk-common:1.15.0`
- Shared code for metrics/trace implementations (clocks, etc)
- `io.opentelemetry:opentelemetry-sdk-metrics:1.15.0`
- Note: packages here have not changed from the experimental jar...just a jar rename happened.
- `io.opentelemetry:opentelemetry-sdk-all:1.15.0`
- The SDK side of io.opentelemetry:opentelemetry-api:1.15.0