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.

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

Add decision about v2 API #3968

Merged
merged 11 commits into from
Jun 21, 2023
25 changes: 25 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -470,8 +470,33 @@ doumentation are allowed to be extended with additional methods.

> Warning: methods may be added to this interface in minor releases.

These interfaces are defined by the OpenTelemetry specification and will be
updated as the specification evolves.

Otherwise, stable interfaces MUST NOT be modified.

#### How to Change Specification Interfaces

When an API change must be made, we will update the SDK with the new method one
release before the API change. This will allow the SDK one version before the
API change to work seemlessly with the new API.
pellared marked this conversation as resolved.
Show resolved Hide resolved

If an incompatible version of the SDK is used with the new API the application
pellared marked this conversation as resolved.
Show resolved Hide resolved
will fail to compile.

#### How Not to Change Specification Interfaces

We have explored using a v2 of the API to change interfaces and found that there
was no way to introduce a v2 and have it seamlessly work with the v1 of the API.
pellared marked this conversation as resolved.
Show resolved Hide resolved
Problems happened libraries that upgraded to v2 when an application did not
would not produce any telemetry.
MadVikingGod marked this conversation as resolved.
Show resolved Hide resolved

More detail of the approaches considered and their limitations can be found in
the [Use a V2 API to evolve interfaces](https://github.com/open-telemetry/opentelemetry-go/issues/3920)
issue.

#### How to Change Other Interfaces

If new functionality is needed for an interface that cannot be changed it MUST
be added by including an additional interface. That added interface can be a
simple interface for the specific functionality that you want to add or it can
Expand Down