diff --git a/OpenTelemetry.sln b/OpenTelemetry.sln index ecac4cdcbb3..71f573124c3 100644 --- a/OpenTelemetry.sln +++ b/OpenTelemetry.sln @@ -16,6 +16,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution NuGet.config = NuGet.config OpenTelemetry.proj = OpenTelemetry.proj README.md = README.md + VERSIONING.md = VERSIONING.md EndProjectSection EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "build", "build", "{7CB2F02E-03FA-4FFF-89A5-C51F107623FD}" diff --git a/VERSIONING.md b/VERSIONING.md new file mode 100644 index 00000000000..14d71537ae1 --- /dev/null +++ b/VERSIONING.md @@ -0,0 +1,122 @@ +# Versioning details + +This document describes the versioning and stability policy of components +shipped from this repository, as per the [OpenTelemetry versioning and stability +specification](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/versioning-and-stability.md). + +This repo follows [SemVer V2](https://semver.org/spec/v2.0.0.html) guidelines. +This means that, for any stable packages released from this repo, all public +APIs will remain [backward +compatible](https://github.com/dotnet/runtime/blob/master/docs/coding-guidelines/breaking-change-rules.md#breaking-change-rules), +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](https://docs.microsoft.com/dotnet/api/system.obsoleteattribute) +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](https://github.com/dotnet/roslyn-analyzers/tree/master/src/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](https://github.com/open-telemetry/opentelemetry-dotnet/tree/master/src/OpenTelemetry.Instrumentation.AspNetCore/.publicApi) +shows the public APIs, per target framework for the +`OpenTelemetry.Instrumentation.AspNetCore` package. + +Since no stable version has been released so far, every API is listed in the +"Unshipped.txt" file. Once 1.0.0 is shipped, it'll be moved to "Shipped.txt" +file. + +## 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.