Skip to content

Latest commit

 

History

History
93 lines (72 loc) · 4 KB

Versioning.md

File metadata and controls

93 lines (72 loc) · 4 KB

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

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

    #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 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, LOGGING_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.

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