Skip to content

Latest commit

 

History

History
124 lines (96 loc) · 6.04 KB

VERSIONING.md

File metadata and controls

124 lines (96 loc) · 6.04 KB
Raw

Versioning details

This document describes the versioning and stability policy of components shipped from this repository, as per the OpenTelemetry versioning and stability specification.

This repo follows SemVer V2 guidelines. This means that, for any stable packages released from this repo, all public APIs will remain backward compatible, unless a major version bump occurs. This applies to the API, SDK, as well as Exporters, Instrumentation etc. shipped from this repo.

For example, users can take a dependency on 1.0.0 version of any package, with the assurance that all future releases until 2.0.0 will be backward compatible. Any method which is planned to be removed in 2.0, will be marked Obsolete first.

API and SDK compatibility

API packages are supported with an SDK version that has same MAJOR version and equal or greater MINOR or PATCH version. For example, application/library that is instrumented with OpenTelemetry.API 1.1.0, will be compatible with SDK versions [1.1.0, 2.0.0).

Core components

Core components refer to the set of components which are required as per the spec. This includes API, SDK, and exporters which are required by the specification. These exporters are OTLP, Jaeger, Zipkin, Console and InMemory.

The core components are always versioned and released together. For example, if Zipkin exporter has a bug fix and is released as 1.0.1, then all other core components are also released as 1.0.1, even if there is no code change in other components.

Pre-releases

Pre-release packages are denoted by appending identifiers such as -Alpha, -Beta, -RC etc. There are no API guarantees in pre-releases. Each release can contain breaking changes and functionality could be removed as well. In general, an RC pre-release is more stable than a Beta release, which is more stable than an Alpha release.

Public API change detection

For convenience, every project in this repo uses PublicApiAnalyzers and lists public API in the directory "publicAPI". Any changes to public API, without corresponding changes here will result in build breaks - this helps catch any unintended changes to public API from being shipped accidentally. This also helps reviewers quickly understand if a given PR is proposing public API changes. For example, this shows the public APIs, per target framework for the OpenTelemetry.Instrumentation.AspNetCore package.

APIs which are released as part of stable packages will be listed in the "Shipped.txt" file, and those APIs which are released as part of pre-release packages in the "Unshipped.txt". APIs will be moved from "Unshipped.txt" to "Shipped.txt" when the packages move from pre-release to stable.

Packaging

OpenTelemetry is structured around signals like Traces, Metrics, Logs, Baggage etc. OpenTelemetry .NET mostly provides multiple signals in the same package. i.e the OpenTelemetry package will consist of SDK components from all the signals. Instrumentations also follow the same model - for example, there will be a single package OpenTelemetry.Instrumentation.AspNetCore for ASP.NET Core instrumentation, which produces Traces, Metrics and handles propagation, instead of separate packages.

OpenTelemetry .NET relies on .NET runtime to provide several instrumentation APIs. Currently, System.Diagnostics.DiagnosticSource and Microsoft.Extensions.Logging.Abstractions are the packages from .NET runtime this repository is dependent on. In the future, APIs for Metrics, Propagators etc. will also come from .NET runtime itself. Depending on whether .NET runtime choses to use same package or separate package for these, users may be required to install separate packages for instrumenting.

Packaging non-stable signals

Due to the fact that OpenTelemetry specification for different signals achieve stability at different pace, we'll need to deal with shipping non-stable signals. As of Jan 2021, Metrics and Logs specs have not been declared stable. Non-stable signals are shipped as separate non-stable versions of the package to ensure they do not affect the stable signals. Following example demonstrates how non-stable signals are shipped, with the example of Metrics as the non-stable signal. (Actual versions may vary, below numbers are for demonstrating the approach only.)

OpenTelemetry package versioning with stable and non-stable signal (Metrics):

OpenTelemetry 0.7.0-beta1 release : Pre-release, no API guarantees.

OpenTelemetry 1.0.0-rc1 release : Pre-release, no API guarantees, but more stable than beta.

OpenTelemetry 1.0.0 release : Stable release consisting of only stable signals :- Traces, Propagators, Baggage.

OpenTelemetry 1.2.0-alpha release : Pre-release consisting of Metric SDK. Alpha indicates early stages of development. Metric entry points are from the Sdk class. This could be released at the same time as OpenTelemetry 1.0.0 or shortly after that. This may be released from an "experimental-metrics" branch which is in sync with master.

OpenTelemetry 1.0.1 release : Bug fixes to traces. Does not contain any metrics code.

OpenTelemetry 1.1.0 release : New features added to traces. Does not contain any metrics code.

OpenTelemetry 1.2.0-beta release : Metric evolves to beta status. Still a pre-release, so breaking changes can still occur.

OpenTelemetry 1.2.0-rc1 release : Metric evolves to RC status. Still a pre-release, but closer to stable.

OpenTelemetry 1.2.0 release : Stable package consisting of Traces and Metrics. User who were consuming Metrics features from 1.2.0-rc1 requires no code change.