Adding upstream version 18.2.2.upstream/18.2.2

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 107 insertions, 0 deletions

diff --git a/src/jaegertracing/opentelemetry-cpp/Versioning.md b/src/jaegertracing/opentelemetry-cpp/Versioning.md
new file mode 100644
index 000000000..b6cbe490e
--- /dev/null
+++ b/src/jaegertracing/opentelemetry-cpp/Versioning.md
@@ -0,0 +1,107 @@
+# Versioning
+
+This document describes the versioning policy for this repository.
+
+## Goals
+
+### API and SDK Compatibility
+
+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. For example,
+application compiled with API v1.1 is compatible with SDK v1.1.2, v1.2.0, etc.
+
+For example, libraries that are instrumented with `opentelemetry 1.0.1` will
+function in applications using `opentelemetry 1.11.33` or `opentelemetry 1.3.4`,
+buy may not work in applications using `opentelemetry 2.0.0`.
+
+### ABI Stability
+
+Refer to the [ABI Policy](./docs/abi-policy.md) for more details. To summarise:
+
+* The API is header only, and uses ABI compliant interfaces. However, ABI
+  stability is not guaranteed for SDK.
+* In case of ABI breaking changes, a new `inline namespace` version will be
+  introduced, and the existing linked applications can continue using the older
+  version unless they relink with newer version.
+
+## Release Policy
+
+* Release versions will follow [SemVer 2.0](https://semver.org/).
+* Only a single source package containing the API, SDK, and exporters which are
+  required by the specification would be released. All these components are
+  always versioned and released together. For example, any changes in one of the
+  exporter would result in version update of the entire source package even
+  though there is no changes in API, SDK and other exporters.
+* Experimental releases: New (unstable) telemetry signals and features will be
+  introduced behind feature flag protected by a preprocessor macro.
+
+  ```cpp
+  #ifdef FEATURE_FLAG
+    <metrics api/sdk definitions>
+  #endif
+  ```
+
+  As we deliver the package in source form, and the user is responsible to build
+  it for their platform, the user must be aware of these feature flags
+  (documented in the [CHANGELOG.md](CHANGELOG.md) file). The user must enable
+  them explicitly through their build system (CMake, Bazel or others) to use any
+  preview features.
+
+  The guidelines in creating feature flag would be:
+
+  * Naming:
+    * `ENABLE_<SIGNAL>_PREVIEW` : For experimental release of signal api/sdks
+      eg, `METRICS_PREVIEW`, `LOGS_PREVIEW`,
+    * `ENABLE_<SIGNAL>_<FEATURE_NAME>_PREVIEW` : For experimental release for
+      any feature within stable signal. For example, `TRACING_JAEGER_PREVIEW` to
+      release the experimental Jaeger exporter for tracing.
+  * Cleanup: It is good practice to keep feature-flags as shortlived as
+    possible. And, also important to keep the number of them low. They should be
+    used such that it is easy to remove/cleanup them once the experimental
+    feature is stable.
+
+* New signals will be stabilized via a **minor version bump**, and are not
+  allowed to break existing stable interfaces. Feature flags will be removed
+  once we have a stable implementation for the signal.
+
+* As an exception, small experimental features in otherwise stable
+  signals/components mayn't necessarily be released under feature flag. These
+  would be flagged as experimental by adding a `NOTE` in it's header file -
+  either at the beginning of file, or as the comment for the experimental API
+  methods. Also, if the complete header is experimental, it would be prefixed as
+  `experimental_`. As an example, the semantic conventions for trace signal is
+  experimental at the time of the writing and is within
+  `experimental_semantic_conventions.h`
+
+* Code under the "*::detail" namespace implements internal details, and is NOT
+  part of public interface. Also, any API not documented in the [public
+  documentation](https://opentelemetry-cpp.readthedocs.io/en/latest/) is NOT
+  part of the public interface.
+
+* GitHub releases will be made for all released versions.
+
+## Example Versioning Lifecycle
+
+Purely for illustration purposes, not intended to represent actual releases:
+
+* v0.0.1 release:
+  * Contains experimental API and SDK of trace (without feature flag)
+  * No API and SDK of logging and metrics available
+* v1.0.0-rc1 release:
+  * Pre-release, no API/ABI guarantees, but more stable than alpha/beta.
+  * Contains pre-release API and SDK of trace, baggage and resource
+  * experimental metrics and logging API/SDK behind feature flag
+* v1.0.0: ( with traces )
+  * Contains stable API and SDK of trace, baggage and resource
+  * experimental metrics and logging API/SDK behind feature flag
+* v1.5.0 release (with metrics)
+  * Contains stable API and SDK of metrics, trace, baggage, resource.
+  * experimental logging API/SDK behind feature flag
+* v1.10.0 release (with logging)
+  * Contains stable API and SDK of logging, metrics, trace, baggage, resource.
+
+### Before moving to version 1.0.0
+
+* Major version zero (0.y.z) is for initial development. Anything MAY change at
+  any time. The public API SHOULD NOT be considered stable.