View Source Versioning and Releasing
OTP Applications and the OpenTelemetry Spec itself use semver v2.
In this document, references to OTP concepts are distinguished by capitalizing the word (for example Application and Release) while the generic term (like release) is lowercase.
module-prefix
Module Prefix
The module prefix for all modules in any of these core Applications is
otel
. This means modules can move between Applications without their name
changing. Because of Erlang's flat namespace, there is no code for a user to change
when an API graduates from experimental to stable, if the user was
using the latest version of the experimental API.
This also allows flexibility for modules that might be in the SDK but are found to be better placed in the API, or vice versa. This has happened a few times in the pre-1.0 world as functionality was floating from SDK to API at times.
otp-applications
OTP Applications
experimental-api-opentelemetry_api_experimental
Experimental API (opentelemetry_api_experimental
)
The experimental package is where any API that is not stable when 1.0 is released MUST live. At this time (prior to 1.0) that means Metrics and Logging.
This package will always be 0.x because it is never stable and modules will be removed when they are moved to the stable API package. Breaking changes, as well as non-trivial additions, to the experimental API will only result in a minor version bump.
api-opentelemetry_api
API (opentelemetry_api
)
The API package must provide semver-defined backwards-compatibility
once a major version (e.g. 1.0.0) is released. When a particular part of the API
becomes stable, its modules are moved from opentelemetry_api_experimental
to
opentelemetry_api
and a new minor release of both is published.
At the release of version 1.0, the following signal APIs will be included
in opentelemetry_api
:
- Tracing
- Baggage
- Context
experimental-sdk-opentelemetry_sdk_experimental
Experimental SDK (opentelemetry_sdk_experimental
)
The experimental SDK contains the implementations for the APIs in the
experimental API of the same minor version. For example, there may be
multiple patch-level releases (v0.3.2
, v0.3.3
) of the experimental
SDK for each minor version of the experimental API (v0.3.0
).
Any setup for signals contained in the experimental SDK must be done on startup
of the experimental SDK. For example, setting the default Meter would be done
in start/2
of opentelemetry_sdk_experimental
.
sdk-opentelemetry
SDK (opentelemetry
)
Functionality is implemented in this Application and the API is dynamically configured to use a particular SDK -- at this time there is only 1 SDK implementation, the default implementation.
A goal is that the latest SDK can always be used with any version of the API, so that a user can always pull the latest implementation into their final Release to run with any API versions that were used in instrumented Applications within the Release.
otlp-exporter-opentelemetry_exporter
OTLP Exporter (opentelemetry_exporter
)
Exporter implementations are tied to the SDK's public API.
releases
Releases
experimental-api
Experimental API
As noted in the previous section, opentelemetry_api_experimental
is versioned
separately from the rest and will always remain 0.x.
api
API
Additions to the API are released with minor version bumps.
experimental-sdk
Experimental SDK
As noted in the previous section, opentelemetry_sdk_experimental
is versioned
separately from the rest, but in lockstep with opentelemetry_api_experimental
,
and will always remain 0.x.
sdk
SDK
Additions to the SDK are released with minor version bumps.
deprecation
Deprecation
Code is only marked as deprecated when the replacement is stable.
Unlikely example: There is a Tracing v2 spec defined. The module will be named
otel_trace2
and the functions in otel_trace
marked as deprecated.
Deprecated functions must be marked with -deprecated
in the module so that
xref
provides a warning about usage to the user.
removal
Removal
A major version bump is required to remove a signal or module.
In the unlikely example mentioned in the Deprecation section, this step would mean removal of the
original module (otel_trace
) and a major version bump release.
examples
Examples
Purely for illustration purposes, not intended to represent actual releases:
- v1.0.0 release:
opentelemetry_api
1.0.0- Contains APIs for tracing, baggage, propagators
opentelemetry_api_experimental
0.2.0- Contains APIs for metrics
opentelemetry_sdk
1.0.0opentelemetry_sdk_experimental
0.2.0
- v1.15.0 release (with metrics)
opentelemetry_api
1.15.0- Contains APIs for tracing, baggage, propagators, metrics
opentelemetry_api_experimental
0.42.0- No longer contains APIs for metrics
opentelemetry_sdk
1.15.0opentelemetry_sdk_experimental
0.42.0