> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/open-telemetry/opentelemetry-rust/llms.txt
> Use this file to discover all available pages before exploring further.
# Versioning Policy
> Understand the versioning policy for OpenTelemetry Rust, including API stability guarantees, SDK compatibility, and release lifecycle.
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.
## Versioning Policy
OpenTelemetry Rust follows these versioning principles:
### Semantic Versioning
All releases follow [SemVer 2.0.0](https://semver.org/):
* **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](https://doc.rust-lang.org/cargo/reference/features.html):
```toml theme={null}
[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](https://crates.io)
* Release notes follow the [conventional commits](https://www.conventionalcommits.org/) 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:
1. **Deprecation** - Features are deprecated in a minor release with warnings
2. **Migration period** - At least one minor version cycle for users to migrate
3. **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:
```toml theme={null}
[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:
1. Check if it's a known issue in the [GitHub issues](https://github.com/open-telemetry/opentelemetry-rust/issues)
2. For version-specific issues, include your `Cargo.toml` dependencies
3. Report regressions immediately - they are considered high priority
Use the bug report template to help maintainers investigate version-related issues.