Versioning Policy

This document describes the versioning policy for the OpenTelemetry Rust repository. This policy is designed to provide stability guarantees while allowing the project to evolve.

Goals

API Stability

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.

Libraries instrumented with opentelemetry 1.0.1 will function in applications using opentelemetry 1.11.33 or opentelemetry 1.3.4.

This stability guarantee ensures that:

Application developers can upgrade the SDK without breaking instrumented libraries
Library authors can instrument their code knowing it will work across SDK versions
The ecosystem can evolve without forcing coordinated updates

SDK Stability

Public portions of the SDK (constructors, configuration, end-user interfaces) must remain backwards compatible. Internal types are allowed to break between minor versions.

Only public APIs are guaranteed backwards compatibility. Internal implementation details may change.

OpenTelemetry Rust follows these versioning principles:

Semantic Versioning

All releases follow SemVer 2.0.0:

Major version (X.0.0) - Breaking changes to public APIs
Minor version (0.X.0) - New features, stabilization of experimental features
Patch version (0.0.X) - Bug fixes, performance improvements

Experimental Features

New telemetry signals are introduced behind experimental cargo features:

[dependencies]
opentelemetry = { version = "1.0", features = ["metrics-experimental"] }

New signals are stabilized via a minor version bump and are not allowed to break existing stable interfaces.

Release Artifacts

GitHub releases are created for all released versions
Crates are published to crates.io
Release notes follow the conventional commits format

Example Versioning Lifecycle

To better understand how this policy works in practice, here’s an example of how the metrics and logging signals could stabilize:

v1.0.0 release

opentelemetry 1.0.0

Contains stable implementations of trace, baggage, resource, context modules
Experimental metrics implementation behind feature flag

opentelemetry-semantic-conventions 1.0.0

Contains stable implementations of trace, resource conventions
Experimental metrics conventions behind feature flag

opentelemetry-contrib 1.0.0

Contains stable implementations of 3rd party trace exporters and propagators
Experimental metrics exporters and propagator implementations behind feature flag

v1.5.0 release (stabilizing metrics)

opentelemetry 1.5.0

Contains stable implementations of metrics, trace, baggage, resource, context modules
Experimental logging implementation still behind feature flag

opentelemetry-semantic-conventions 1.2.0

Contains stable implementations of metrics, trace, resource conventions
Experimental logging conventions still behind feature flag

opentelemetry-contrib 1.6.0

Contains stable implementations of 3rd party trace and metrics exporters and propagators
Experimental logging exporters and propagator still behind feature flag

v1.10.0 release (stabilizing logging)

opentelemetry 1.10.0

Contains stable implementations of logging, metrics, trace, baggage, resource, context modules

opentelemetry-semantic-conventions 1.4.0

Contains stable implementations of logging, metrics, trace, resource conventions

opentelemetry-contrib 1.12.0

Contains stable implementations of 3rd party trace, metrics, and logging exporters and propagators

Breaking Changes

Breaking changes are taken seriously and follow this process:

Deprecation - Features are deprecated in a minor release with warnings
Migration period - At least one minor version cycle for users to migrate
Breaking change - Removal happens in the next major version

Internal APIs (types not exposed in public documentation) may change between minor versions without following the deprecation process.

Feature Flags and Stability

Stable Features

Features without the experimental or unstable suffix are considered stable and follow the semantic versioning guarantees:

traces - Stable tracing signal
metrics - Stable metrics signal
logs - Stable logging signal
rt-tokio - Tokio runtime support

Unstable Features

Features marked with otel_unstable are experimental and may change at any time:

[dependencies]
opentelemetry = { version = "1.0", features = ["otel_unstable"] }

APIs behind otel_unstable may have breaking changes in minor versions. Use in production at your own risk.

Version Compatibility Matrix

Component	API Version	SDK Version	Compatible?
App using SDK 1.0.0	Library instrumented with 1.0.0	1.0.0	✅ Yes
App using SDK 1.5.0	Library instrumented with 1.0.0	1.5.0	✅ Yes
App using SDK 1.0.0	Library instrumented with 1.5.0	1.0.0	❌ No
App using SDK 2.0.0	Library instrumented with 1.0.0	2.0.0	❌ No

Release Cadence

While there is no fixed release schedule, the project generally follows these patterns:

Patch releases - As needed for bug fixes
Minor releases - Every 4-8 weeks for new features
Major releases - When necessary for breaking changes (infrequent)

Reporting Issues

If you encounter a bug or unexpected behavior:

Check if it’s a known issue in the GitHub issues
For version-specific issues, include your Cargo.toml dependencies
Report regressions immediately - they are considered high priority

File a Bug Report

Use the bug report template to help maintainers investigate version-related issues.

Community

Versioning Policy

Goals

API Stability

SDK Stability