From 5767f8e4a2cd32e8ab8647fc5eb672a5e3c21ed6 Mon Sep 17 00:00:00 2001 From: Lalit Kumar Bhasin Date: Wed, 2 Jun 2021 00:39:57 +0530 Subject: [PATCH] Versioning doc update (#811) --- Versioning.md | 74 ++++++++++++++++++--------------------------------- 1 file changed, 26 insertions(+), 48 deletions(-) diff --git a/Versioning.md b/Versioning.md index 51feaf7052..b95fc77650 100644 --- a/Versioning.md +++ b/Versioning.md @@ -4,7 +4,7 @@ This document describes the versioning policy for this repository. ## Goals -### API Stability +### API and SDK Compatibility Once the API for a given signal (spans, logs, metrics, baggage) has been officially released, that API module will function with any SDK that has the @@ -12,32 +12,27 @@ same MAJOR version and equal or greater MINOR or PATCH version. For example, application compiled with API v1.1 is compatible with SDK v1.1.2, v1.2.0, etc. For example, libraries that are instrumented with `opentelemetry 1.0.1` will -function in applications using `opentelemetry 1.11.33` or `opentelemetry 1.3.4`. - -### SDK Stability - -Public portions of the SDK (constructors, configuration, end-user interfaces) -must remain backwards compatible. Internal types are allowed to break. +function in applications using `opentelemetry 1.11.33` or `opentelemetry 1.3.4`, +buy may not work in applications using `opentelemetry 2.0.0`. ### ABI Stability Refer to the [ABI Policy](./docs/abi-policy.md) for more details. To summarise: -* ABI stability is guaranteed for the API. -* ABI stability is not guaranteed for the SDK. In case of ABI breaking changes, - instead of bumping up the major version, a new `inline namespace` version will - be created, and both old API and new API would be made available - simultaneously. +* The API is header only, and uses ABI compliant interfaces. However, ABI stability + is not guaranteed for SDK. +* In case of ABI breaking changes, a new `inline namespace` version will + be introduced, and the existing linked applications can continue using the older version + unless they relink with newer version. -## Policy +## Release Policy * Release versions will follow [SemVer 2.0](https://semver.org/). -* Only a single source package containing both the api and sdk for all signals - will be released as part of each GitHub release. -* There will be source package releases for api and sdk. There won't be separate - releases for the signals. The release version numbers for api and sdk will not - be in sync with each other. As there would be more frequent changes expected - in sdk than in the api. +* Only a single source package containing the API, SDK, and exporters which are + required by the specification would be released. All these components are + always versioned and released together. For example, any changes in one of the exporter + would result in version update of the entire source package even though there is + no changes in API, SDK and other exporters. * Experimental releases: New (unstable) telemetry signals and features will be introduced behind feature flag protected by a preprocessor macro. @@ -77,37 +72,20 @@ Refer to the [ABI Policy](./docs/abi-policy.md) for more details. To summarise: Purely for illustration purposes, not intended to represent actual releases: * v0.0.1 release: - * `opentelemetry-api 0.0.1` - * Contains experimental api's of trace, resouce ( no feature flag as major - version is 0 ) - * No api's of logging and metrics available - * `opentelemetry-sdk 0.0.1` - * Contains experimental implementation of trace, resouce ( no feature flag - as major version is 0 ) - * No implemtation of logging and metrics available -* v1.0.0 release: ( with traces ) - * `opentelemetry-api 1.0.0` - * Contains stable apis of trace, baggage and resource - * experimental metrics api's behind feature flag - * `opentelemetry-sdk 1.0.0` - * Contains stable implementation of trace, baggage and resource - * experimental metrics api's behind feature flag + * Contains experimental API and SDK of trace (without feature flag) + * No API and SDK of logging and metrics available +* v1.0.0-rc1 release: + * Pre-release, no API/ABI guarantees, but more stable than alpha/beta. + * Contains pre-release API and SDK of trace, baggage and resource + * experimental metrics and logging API/SDK behind feature flag +* v1.0.0: ( with traces ) + * Contains stable API and SDK of trace, baggage and resource + * experimental metrics and logging API/SDK behind feature flag * v1.5.0 release (with metrics) - * `opentelemetry-api 1.5.0` - * Contains stable api's of metrics, trace, baggage, resource, context - modules - * experimental logging api still only behind feature flag - * `opentelemetry-sdk 1.5.0` - * Contains stable implementation of metrics, trace, baggage, resource, - context modules - * experimental logging implementation still only behind feature flag + * Contains stable API and SDK of metrics, trace, baggage, resource. + * experimental logging API/SDK behind feature flag * v1.10.0 release (with logging) - * `opentelemetry-api 1.10.0` - * Contains stable api's of logging, metrics, trace, baggage, resource, - context modules - * `opentelemetry-sdk 1.10.0` - * Contains stable sdk of logging, metrics, trace, baggage, resource, context - modules + * Contains stable API and SDK of logging, metrics, trace, baggage, resource. ### Before moving to version 1.0.0