87 lines
2.9 KiB
Markdown
87 lines
2.9 KiB
Markdown
# Versioning
|
|
|
|
This document defines the stability guarantees offered by
|
|
the OpenTelemetry .NET Automatic Instrumentation,
|
|
along with the rules and procedures for meeting those guarantees.
|
|
|
|
This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
|
|
with one exception described [here](#compatibility-with-opentelemetry-net-and-other-dependencies).
|
|
|
|
## Release candidates
|
|
|
|
Release candidates are having the `-rc.N` pre-release label.
|
|
|
|
## Beta releases
|
|
|
|
Beta (experimental) releases are having the `-beta.N` pre-release label.
|
|
|
|
## Compatibility with OpenTelemetry .NET and other dependencies
|
|
|
|
OpenTelemetry .NET Automatic Instrumentation is built on top of
|
|
[OpenTelemetry .NET](https://github.com/open-telemetry/opentelemetry-dotnet).
|
|
Unfortunately, this may cause dependency version conflicts
|
|
if the instrumented application is referencing the same assemblies
|
|
as OpenTelemetry .NET Automatic Instrumentation.
|
|
|
|
The [troubleshooting document](troubleshooting.md) describes
|
|
how to resolve such conflicts.
|
|
|
|
This may be seen as a "breaking change" from the user
|
|
perspective, but unfortunately it is currently unavoidable
|
|
and bumping a major version during each dependency version bump
|
|
would be an overkill.
|
|
|
|
## Semantic Conventions stability
|
|
|
|
See [here](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/versioning-and-stability.md#semantic-conventions-stability).
|
|
|
|
## Major version bump
|
|
|
|
There are a few cases when a major bump may occur.
|
|
|
|
* Breaking change of a stable functionality or configuration.
|
|
* Removal of a stable functionality or configuration.
|
|
|
|
**Exception:** Changes related to instrumentation libraries are handled
|
|
the same way as experimental features.
|
|
|
|
Major versions bumps are avoided.
|
|
|
|
## Minor version bump
|
|
|
|
Most changes result in a minor version bump.
|
|
|
|
* Addition of new functionality, configuration, or instrumentation library.
|
|
* Making experimental functionality or configuration stable.
|
|
* Backwards compatible change in a stable functionality or configuration.
|
|
* Deprecation of a stable functionality.
|
|
* Dependency bump which may affect the user.
|
|
|
|
Changes related to the instrumentation libraries:
|
|
|
|
* Change (can be breaking) in a supported instrumentation library's
|
|
functionality or configuration.
|
|
* Removal or deprecation of an instrumentation library.
|
|
|
|
Changes related to the experimental features:
|
|
|
|
* Change (can be breaking) in an experimental functionality or configuration.
|
|
* Removal of an experimental functionality or configuration.
|
|
|
|
### Patch version bump
|
|
|
|
Patch versions make no changes that would require recompilation
|
|
or potentially break application code.
|
|
The following are examples of patch fixes.
|
|
|
|
* Bug fixes that do not require minor version bumps per rules above.
|
|
* Security fixes.
|
|
|
|
## Version numbers before 1.0.0
|
|
|
|
We simply convert the Semantic Versioning scheme from
|
|
`MAJOR.MINOR.PATCH` to `0.MAJOR.MINOR`.
|
|
|
|
The changes that would bump the patch version
|
|
are bumping the minor version instead.
|