-
Notifications
You must be signed in to change notification settings - Fork 104
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'main' into exporter-fail
- Loading branch information
Showing
1 changed file
with
133 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,133 @@ | ||
# 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. | ||
|
||
[OTP]: http://erlang.org/doc/system_architecture_intro/sys_arch_intro.html | ||
[OpenTelemetry Spec]: https://github.com/open-telemetry/opentelemetry-specification | ||
[semver v2]: https://semver.org/spec/v2.0.0.html | ||
|
||
## 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 | ||
|
||
### 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. | ||
[MUST]: https://tools.ietf.org/html/rfc2119#section-1 | ||
|
||
### 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`) | ||
|
||
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`) | ||
|
||
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`) | ||
|
||
Exporter implementations are tied to the SDK's public API. | ||
|
||
## Releases | ||
|
||
### Experimental API | ||
|
||
As noted in the previous section, `opentelemetry_api_experimental` is versioned | ||
separately from the rest and will always remain 0.x. | ||
|
||
### API | ||
|
||
Additions to the API are released with minor version bumps. | ||
|
||
### 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 | ||
|
||
Additions to the SDK are released with minor version bumps. | ||
|
||
## 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 | ||
|
||
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 | ||
|
||
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.0 | ||
- `opentelemetry_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.0 | ||
- `opentelemetry_sdk_experimental` 0.42.0 | ||
|