Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add rationale document with versioning/releasing details #1460

Merged
merged 7 commits into from
Jan 19, 2021
Merged
Changes from 1 commit
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
Prev Previous commit
Next Next commit
update
lzchen committed Jan 12, 2021
commit 7a7293fc6f2641e1e0b7e9334953221f8930e964
106 changes: 28 additions & 78 deletions rationale.md
Original file line number Diff line number Diff line change
@@ -21,91 +21,41 @@ For example, libraries that are instrumented with `opentelemetry-api 1.0.1` will
Public portions of the SDK (constructors, configuration, end-user interfaces) must remain backwards compatible.
Internal interfaces are allowed to break.
Copy link
Contributor

Choose a reason for hiding this comment

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

Must they always remain backward compatible? Could an SDK release a v2 or v3 that introduce breaking changes to SDK but still confirms to API 1.x? I know this shouldn't ideally happen but does the spec allow it?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

This is taken right from the specs. Spec enforces backwards compatibility between SDK versions. My understanding is that a breaking change requires a major version bump (from 1.X.Y -> 2.0.0).


## OpenTelemetry Applications
## Methods

### Experimental API (`opentelemetry-api-experimental`)
### Mature Signals
API modules for mature (i.e. released) signals will be included in the `opentelemetry-api` module.

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.
### Immature or experimental signals
API modules for experimental signals will not be included in the `opentelemetry-api` module, and must be installed manually. API modules will remain at version v0.x.y to make it abundantly clear that depending on them is at your own risk. For example, the `opentelemetry-metrics-api` v0.x.y module will provide experimental access to the unfinished metrics API. NO STABILITY GUARANTEES ARE MADE.

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.

### API (`opentelemetry-api`)

The API package is the stable API package that we must provide semver defined
backwards compatibility once a major (1.0) release is made. When an 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 time of 1.0 the following APIs will live in the `opentelemetry-api`
package:

* Tracing
* Baggage
* Context

### Experimental SDK (`opentelemetry-sdk-experimental`)

The experimental SDK contains the implementations for the APIs in the
experimental API of the same version.

This Application is versioned in lockstep with the experimental API and will
never go above 0.x.

### SDK (`opentelemetry-sdk`)

Functionality is implemented in this Application and the API is dynamically
configured to use a particular SDK -- at this time there is only one 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 that was used in instrumented Applications within the
Release.

## 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
## Examples

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.
Purely for illustration purposes, not intended to represent actual releases:

### SDK
#### V1.0.0 Release (tracing, baggage, propagators, context)

Additions to the SDK are released with minor version bumps.
- `opentelemetry-api` 1.0.0
- Contains APIs for tracing, baggage, propagators, context
- `opentelemetry-tracing` 1.0.0
- Contains the tracing SDK
- `opentelemetry-sdk` 1.0.0
- Contains SDK components for tracing, baggage, propagators, and context

## Removal
##### Contains the following experimental packages

A major version bump is required to remove a signal or module.
- `opentelemetry-api-metrics` 0.x.y
- Contains the EXPERIMENTAL API for metrics. There are no stability guarantees.
- `opentelemetry-metrics` 0.x.y
- Contains the EXPERIMENTAL SDK for metrics. There are no stability guarantees.

## Examples

Purely for illustration purposes, not intended to represent actual releases:
#### V1.15.0 Release (with metrics)

- v1.0.0 release:
- `opentelemetry-api` 1.0.0
- Contains APIs for tracing, baggage, propagators
- `opentelemetry-api-experimental` 0.2.0
- `opentelemetry-sdk` 1.0.0
- `opentelemetry-sdk-experimental` 0.2.0
- v1.5.0 release (with metrics)
- `opentelemetry-api` 1.5.0
- Contains APIs for tracing, baggage, propagators, metrics
- `opentelemetry-api-experimental` 0.3.0
- `opentelemetry-sdk` 1.5.0
- `opentelemetry-sdk-experimental` 0.3.0
- v1.10.0 release (with logging)
- `opentelemetry-api` 1.10.0
- Contains APIs for tracing, baggage, propagators, metrics, logging
- `opentelemetry-sdk` 1.10.0
- `opentelemetry-api` 1.15.0
- Contains APIs for tracing, baggage, propagators, context, and metrics
- `opentelemetry-tracing` 1.15.0
- Contains tracing SDK
- `opentelemetry-metrics` 1.15.0
- Contains metrics SDK
- `opentelemetry-sdk` 1.15.0
- Contains SDK components for tracing, baggage, propagators, context and metrics