# Versioning

This document describes the versioning policy for this repository.

## Goals

### 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
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`,
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:

* 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.

## Release Policy

* Release versions will follow [SemVer 2.0](https://semver.org/).
* 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.

  ```cpp
  #ifdef FEATURE_FLAG
    <metrics api/sdk definitions>
  #endif
  ```

  As we deliver the package in source form, and the user is responsible to build
  it for their platform, the user must be aware of these feature flags
  (documented in the [CHANGELOG.md](CHANGELOG.md) file). The user must enable
  them explicitly through their build system (CMake, Bazel or others) to use any
  preview features.

  The guidelines in creating feature flag would be:

  * Naming:
    * `ENABLE_<SIGNAL>_PREVIEW` : For experimental release of signal api/sdks
      eg, `METRICS_PREVIEW`, `LOGS_PREVIEW`,
    * `ENABLE_<SIGNAL>_<FEATURE_NAME>_PREVIEW` : For experimental release for
      any feature within stable signal. For example, `TRACING_JAEGER_PREVIEW` to
      release the experimental Jaeger exporter for tracing.
  * Cleanup: It is good practice to keep feature-flags as shortlived as
    possible. And, also important to keep the number of them low. They should be
    used such that it is easy to remove/cleanup them once the experimental
    feature is stable.

* New signals will be stabilized via a **minor version bump**, and are not
  allowed to break existing stable interfaces. Feature flags will be removed
  once we have a stable implementation for the signal.

* As an exception, small experimental features in otherwise stable
  signals/components mayn't necessarily be released under feature flag. These
  would be flagged as experimental by adding a `NOTE` in it's header file -
  either at the beginning of file, or as the comment for the experimental API
  methods. Also, if the complete header is experimental, it would be prefixed as
  `experimental_`. As an example, the semantic conventions for trace signal is
  experimental at the time of the writing and is within
  `experimental_semantic_conventions.h`

* Code under the "*::detail" namespace implements internal details, and is NOT
  part of public interface. Also, any API not documented in the [public
  documentation](https://opentelemetry-cpp.readthedocs.io/en/latest/) is NOT
  part of the public interface.

* GitHub releases will be made for all released versions.

## Example Versioning Lifecycle

Purely for illustration purposes, not intended to represent actual releases:

* v0.0.1 release:
  * 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)
  * Contains stable API and SDK of metrics, trace, baggage, resource.
  * experimental logging API/SDK behind feature flag
* v1.10.0 release (with logging)
  * Contains stable API and SDK of logging, metrics, trace, baggage, resource.

### Before moving to version 1.0.0

* Major version zero (0.y.z) is for initial development. Anything MAY change at
  any time. The public API SHOULD NOT be considered stable.