Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Versioning doc update #811

Merged
merged 2 commits into from
Jun 1, 2021
Merged

Versioning doc update #811

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
de905ea
Versioning doc update
lalitb Jun 1, 2021
08669d9
Versioning doc update
lalitb Jun 1, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 26 additions & 48 deletions Versioning.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,40 +4,35 @@ This document describes the versioning policy for this repository.

## Goals

### API Stability
### 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`.

### SDK Stability

Public portions of the SDK (constructors, configuration, end-user interfaces)
must remain backwards compatible. Internal types are allowed to break.
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:

* ABI stability is guaranteed for the API.
* ABI stability is not guaranteed for the SDK. In case of ABI breaking changes,
instead of bumping up the major version, a new `inline namespace` version will
be created, and both old API and new API would be made available
simultaneously.
* 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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we give an example here on inline namespace?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry seems i missed this comment. ABI versioning using inline namespace is handled here in the code:

opentelemetry-cpp/api/include/opentelemetry/version.h

Lines 13 to 14 in 5767f8e

#define OPENTELEMETRY_BEGIN_NAMESPACE \
namespace opentelemetry { inline namespace OPENTELEMETRY_CONCAT(v, OPENTELEMETRY_ABI_VERSION_NO) {
. Should I be adding reference to this ?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I think we could add a reference in the next doc update.

unless they relink with newer version.

## Policy
## Release Policy

* Release versions will follow [SemVer 2.0](https://semver.org/).
* Only a single source package containing both the api and sdk for all signals
will be released as part of each GitHub release.
* There will be source package releases for api and sdk. There won't be separate
releases for the signals. The release version numbers for api and sdk will not
be in sync with each other. As there would be more frequent changes expected
in sdk than in the api.
* 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.

Expand Down Expand Up @@ -77,37 +72,20 @@ Refer to the [ABI Policy](./docs/abi-policy.md) for more details. To summarise:
Purely for illustration purposes, not intended to represent actual releases:

* v0.0.1 release:
* `opentelemetry-api 0.0.1`
* Contains experimental api's of trace, resouce ( no feature flag as major
version is 0 )
* No api's of logging and metrics available
* `opentelemetry-sdk 0.0.1`
* Contains experimental implementation of trace, resouce ( no feature flag
as major version is 0 )
* No implemtation of logging and metrics available
* v1.0.0 release: ( with traces )
* `opentelemetry-api 1.0.0`
* Contains stable apis of trace, baggage and resource
* experimental metrics api's behind feature flag
* `opentelemetry-sdk 1.0.0`
* Contains stable implementation of trace, baggage and resource
* experimental metrics api's behind feature flag
* 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)
* `opentelemetry-api 1.5.0`
* Contains stable api's of metrics, trace, baggage, resource, context
modules
* experimental logging api still only behind feature flag
* `opentelemetry-sdk 1.5.0`
* Contains stable implementation of metrics, trace, baggage, resource,
context modules
* experimental logging implementation still only behind feature flag
* Contains stable API and SDK of metrics, trace, baggage, resource.
* experimental logging API/SDK behind feature flag
* v1.10.0 release (with logging)
* `opentelemetry-api 1.10.0`
* Contains stable api's of logging, metrics, trace, baggage, resource,
context modules
* `opentelemetry-sdk 1.10.0`
* Contains stable sdk of logging, metrics, trace, baggage, resource, context
modules
* Contains stable API and SDK of logging, metrics, trace, baggage, resource.

### Before moving to version 1.0.0

Expand Down