projects / ceph.git / blame
| Commit | Line | Data |
|---|---|---|
| 1e59de90 TL |
1 | # Versioning |
| 2 | ||
| 3 | This document describes the versioning policy for this repository. | |
| 4 | ||
| 5 | ## Goals | |
| 6 | ||
| 7 | ### API and SDK Compatibility | |
| 8 | ||
| 9 | Once the API for a given signal (spans, logs, metrics, baggage) has been | |
| 10 | officially released, that API module will function with any SDK that has the | |
| 11 | same MAJOR version and equal or greater MINOR or PATCH version. For example, | |
| 12 | application compiled with API v1.1 is compatible with SDK v1.1.2, v1.2.0, etc. | |
| 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 1.3.4`, | |
| 16 | buy may not work in applications using `opentelemetry 2.0.0`. | |
| 17 | ||
| 18 | ### ABI Stability | |
| 19 | ||
| 20 | Refer to the [ABI Policy](./docs/abi-policy.md) for more details. To summarise: | |
| 21 | ||
| 22 | * The API is header only, and uses ABI compliant interfaces. However, ABI | |
| 23 | stability is not guaranteed for SDK. | |
| 24 | * In case of ABI breaking changes, a new `inline namespace` version will be | |
| 25 | introduced, and the existing linked applications can continue using the older | |
| 26 | version unless they relink with newer version. | |
| 27 | ||
| 28 | ## Release Policy | |
| 29 | ||
| 30 | * Release versions will follow [SemVer 2.0](https://semver.org/). | |
| 31 | * Only a single source package containing the API, SDK, and exporters which are | |
| 32 | required by the specification would be released. All these components are | |
| 33 | always versioned and released together. For example, any changes in one of the | |
| 34 | exporter would result in version update of the entire source package even | |
| 35 | though there is no changes in API, SDK and other exporters. | |
| 36 | * Experimental releases: New (unstable) telemetry signals and features will be | |
| 37 | introduced behind feature flag protected by a preprocessor macro. | |
| 38 | ||
| 39 | ```cpp | |
| 40 | #ifdef FEATURE_FLAG | |
| 41 | <metrics api/sdk definitions> | |
| 42 | #endif | |
| 43 | ``` | |
| 44 | ||
| 45 | As we deliver the package in source form, and the user is responsible to build | |
| 46 | it for their platform, the user must be aware of these feature flags | |
| 47 | (documented in the [CHANGELOG.md](CHANGELOG.md) file). The user must enable | |
| 48 | them explicitly through their build system (CMake, Bazel or others) to use any | |
| 49 | preview features. | |
| 50 | ||
| 51 | The guidelines in creating feature flag would be: | |
| 52 | ||
| 53 | * Naming: | |
| 54 | * `ENABLE_<SIGNAL>_PREVIEW` : For experimental release of signal api/sdks | |
| 55 | eg, `METRICS_PREVIEW`, `LOGS_PREVIEW`, | |
| 56 | * `ENABLE_<SIGNAL>_<FEATURE_NAME>_PREVIEW` : For experimental release for | |
| 57 | any feature within stable signal. For example, `TRACING_JAEGER_PREVIEW` to | |
| 58 | release the experimental Jaeger exporter for tracing. | |
| 59 | * Cleanup: It is good practice to keep feature-flags as shortlived as | |
| 60 | possible. And, also important to keep the number of them low. They should be | |
| 61 | used such that it is easy to remove/cleanup them once the experimental | |
| 62 | feature is stable. | |
| 63 | ||
| 64 | * New signals will be stabilized via a **minor version bump**, and are not | |
| 65 | allowed to break existing stable interfaces. Feature flags will be removed | |
| 66 | once we have a stable implementation for the signal. | |
| 67 | ||
| 68 | * As an exception, small experimental features in otherwise stable | |
| 69 | signals/components mayn't necessarily be released under feature flag. These | |
| 70 | would be flagged as experimental by adding a `NOTE` in it's header file - | |
| 71 | either at the beginning of file, or as the comment for the experimental API | |
| 72 | methods. Also, if the complete header is experimental, it would be prefixed as | |
| 73 | `experimental_`. As an example, the semantic conventions for trace signal is | |
| 74 | experimental at the time of the writing and is within | |
| 75 | `experimental_semantic_conventions.h` | |
| 76 | ||
| 77 | * Code under the "*::detail" namespace implements internal details, and is NOT | |
| 78 | part of public interface. Also, any API not documented in the [public | |
| 79 | documentation](https://opentelemetry-cpp.readthedocs.io/en/latest/) is NOT | |
| 80 | part of the public interface. | |
| 81 | ||
| 82 | * GitHub releases will be made for all released versions. | |
| 83 | ||
| 84 | ## Example Versioning Lifecycle | |
| 85 | ||
| 86 | Purely for illustration purposes, not intended to represent actual releases: | |
| 87 | ||
| 88 | * v0.0.1 release: | |
| 89 | * Contains experimental API and SDK of trace (without feature flag) | |
| 90 | * No API and SDK of logging and metrics available | |
| 91 | * v1.0.0-rc1 release: | |
| 92 | * Pre-release, no API/ABI guarantees, but more stable than alpha/beta. | |
| 93 | * Contains pre-release API and SDK of trace, baggage and resource | |
| 94 | * experimental metrics and logging API/SDK behind feature flag | |
| 95 | * v1.0.0: ( with traces ) | |
| 96 | * Contains stable API and SDK of trace, baggage and resource | |
| 97 | * experimental metrics and logging API/SDK behind feature flag | |
| 98 | * v1.5.0 release (with metrics) | |
| 99 | * Contains stable API and SDK of metrics, trace, baggage, resource. | |
| 100 | * experimental logging API/SDK behind feature flag | |
| 101 | * v1.10.0 release (with logging) | |
| 102 | * Contains stable API and SDK of logging, metrics, trace, baggage, resource. | |
| 103 | ||
| 104 | ### Before moving to version 1.0.0 | |
| 105 | ||
| 106 | * Major version zero (0.y.z) is for initial development. Anything MAY change at | |
| 107 | any time. The public API SHOULD NOT be considered stable. |