Add Versioning details

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}"

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.