Skip to content

Commit df3fc30

Browse files
authored
Add versioning documentation (#379)
1 parent 6212399 commit df3fc30

File tree

1 file changed

+66
-0
lines changed

1 file changed

+66
-0
lines changed

VERSIONING.md

+66
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Versioning
2+
3+
This document describes the versioning policy for this repository. This policy
4+
is designed so the following goals can be achieved.
5+
6+
## Goals
7+
8+
### API Stability
9+
10+
Once the API for a given signal (spans, logs, metrics, baggage) has been
11+
officially released, that API module will function with any SDK that has the
12+
same major version, and equal or greater minor or patch version.
13+
14+
For example, libraries that are instrumented with `opentelemetry 1.0.1` will
15+
function in applications using `opentelemetry 1.11.33` or `opentelemetry
16+
1.3.4`.
17+
18+
### SDK Stability
19+
20+
Public portions of the SDK (constructors, configuration, end-user interfaces)
21+
must remain backwards compatible. Internal types are allowed to break.
22+
23+
## Policy
24+
25+
* Releases will follow [SemVer](https://semver.org/).
26+
* New telemetry signals will be introduced behind experimental
27+
[cargo features](https://doc.rust-lang.org/cargo/reference/features.html).
28+
29+
* New signals will be stabilized via a **minor version bump**, and are not
30+
allowed to break existing stable interfaces.
31+
32+
* GitHub releases will be made for all released versions.
33+
* Crates will be released on crates.io
34+
35+
## Example Versioning Lifecycle
36+
37+
To better understand the implementation of the above policy, here is an example
38+
of how the metrics and logging signals **could** stabilize.
39+
40+
- v1.0.0 release:
41+
- `opentelemetry 1.0.0`
42+
- Contains stable impls of trace, baggage, resource, context modules
43+
- experimental metrics impl behind feature flag
44+
- `opentelemetry-semantic-conventions 1.0.0`
45+
- Contains stable impls of trace, resource conventions
46+
- experimental metrics conventions behind feature flag
47+
- `opentelemetry-contrib 1.0.0`
48+
- Contains stable impls of 3rd party trace exporters and propagators
49+
- experimental metrics exporters and propagator impls behind feature flag
50+
- v1.5.0 release (with metrics)
51+
- `opentelemetry 1.5.0`
52+
- Contains stable impls of metrics, trace, baggage, resource, context modules
53+
- experimental logging impl still only behind feature flag
54+
- `opentelemetry-semantic-conventions 1.2.0`
55+
- Contains stable impls of metrics, trace, resource conventions
56+
- experimental logging conventions still only behind feature flag
57+
- `opentelemetry-contrib 1.6.0`
58+
- Contains stable impls of 3rd party trace and metrics exporters and propagators
59+
- experimental logging exporters and propagator still impls behind feature flag
60+
- v1.10.0 release (with logging)
61+
- `opentelemetry 1.10.0`
62+
- Contains stable impls of logging, metrics, trace, baggage, resource, context modules
63+
- `opentelemetry-semantic-conventions 1.4.0`
64+
- Contains stable impls of logging, metrics, trace, resource conventions
65+
- `opentelemetry-contrib 1.12.0`
66+
- Contains stable impls of 3rd party trace, metrics, and logging exporters and propagators

0 commit comments

Comments
 (0)