An upgrade of API from 1.0.3 to 1.1.0 contains breaking changes

[filakhtov]

👋🏻 hey folks,

Just wanted to make sure you are aware of this, but when trying to upgrade the API package from 1.0.3 to 1.1.0 I ran into problems. We are using a custom tracer implementation that implements the usual TracerInterface but enriches things with necessary context and is a composition on top of the actual tracer provided by the SDK. We have a composer version constraints set to ^1.0, which considers everything up to 2.0 as compatible. However, the 1.1.0 just added a new method isEnabled to the interface, breaking our custom tracer implementation with:

Fatal error: Class ContextAwareTracer contains 1 abstract method and must therefore be declared abstract or implement the remaining methods (OpenTelemetry\API\Trace\TracerInterface::isEnabled) in ./ContextAwareTracer.php on line 10

Given this project is following the semantic versioning, this is breaking the expectations.

Cheers,
Garry

[brettmc]

Hi @filakhtov
sorry about that. You're correct that we shouldn't be introducing BC in a minor version. It prompted a discussion in our weekly SIG meeting today. Since the OpenTelemetry spec is evolving and introducing breaking changes, we need to keep better track of BCs, and make major version changes as appropriate.

[t2t2]

There have been similar issues in the past in other languages API & SDK-s (eg. open-telemetry/opentelemetry-js#4142), and it ended up being defined in the spec as (PR):

When new minor versions of the OpenTelemetry API are released, they will contain new features. This includes new interfaces, as well as new methods on current interfaces. SDK maintainers are expected to release new versions which implement these features in a timely manner.

[...]

API changes

When new functionality is added to the OpenTelemetry API, a new minor version of the API is released. These API changes are always additive and backwards compatible from the perspective of existing Instrumentation packages which import and call prior versions. Instrumentation written against all prior minor versions of the API continues to work, and may be composed together into the same application without creating a dependency conflict.

API implementations are expected to always target the latest version of the API. When a new version of the API is released, a version of the SDK which supports the API is released in tandem. Old versions of the SDK are not expected to support newer versions of the API.

So this is actually as-intended by spec and custom implementations should require exact version (maybe ~1.0.0) of otel api

[filakhtov]

@t2t2 something doesn't line up with your story. Versioning for this project indicates use of semver2

opentelemetry-php/docs/versioning.md

Line 2 in 39cc549

This project uses [semver v2](https://semver.org/), as does the rest of OpenTelemetry.

and reading the OpenTelemetry documentation it clearly states:

Backward-incompatible changes to API packages MUST NOT be made unless the major version number is incremented. All existing API calls MUST continue to compile and function against all future minor versions of the same major version.
...

And also https://opentelemetry.io/docs/specs/otel/versioning-and-stability/#version-numbers:

OpenTelemetry clients MUST follow Semantic Versioning 2.0.0, with the following clarifications.
...

Adding a method to the interface is considered a breaking change in many compiled and interpreted languages. Even though adding a method in the spec is considered to be an additive change and can be released as a minor version, this doesn't mean that every language implementation will also have a minor version release.

If I misunderstand the situation, and there is an expectation that spec version is locked down to the implementation version, then we should stop saying that OpenTelemetry follows the semantic versioning, because that's misleading.