Coming from compiled languages: major.minor.patch;

• patch -> can replace the shared library with no changes to client code. (ABI and API are held)
• minor -> requires recompilation (e.g. struct sizes changed in types not held in opaque pointers) (ABI broken; API held)
• major -> requires a client code change. (ABI and API are broken)

As a consumer I consider anything a breaking change that will break my application. IMO behavioral changes are worse than exceptions because they are silent and may impact application in ways that are critical but completely silent. Users could go days or weeks without noticing that their systems are misbehaving. For this reason, I always lock exact versions of my deps and always have reproducible builds. Any random person publishing code somewhere unrelated to my project should never result in my build changing in any way. IMO auto minor/patch version updates are highly overrated and cause a lot more pain than they solve. I wish we could enforce use of lock files and exact dep versions for our users :(

As an OpenTelemetry author, I think if we make any changes that break collection or generation of telemetry data in any way, it should be considered a breaking change. If a change breaks relation between spans by breaking context propagation for example without breaking APIs, I think it should be a breaking change.

I totally see your point of this being harder to define but I think as a SIG we are capable of making judgement calls for such rare cases instead of ignoring an entire set of cases that may break telemetry in customer apps on a simple re-deploy or seemingly innocent dependency upgrade. May be an infinitely expressive type system might have helped we don't have that :)

Here is more information.

Here's the spec doc around backwards compatibility: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/versioning-and-stability.md

Okay let's scope this issue down to specifically just "are changes in behavior breaking changes"? We have all already agreed that we must maintain semver and making changes/removal of API needs to increase in major version.

In theory, any bug fix can be considered a change in behavior and can cause application code to break, right?

@ocelotl Brings up a good point here, and a specific instance can be seen in this pr. This change supposedly fixes an issue where the TraceProvider is instantiated somewhere else and in the users current application, they cannot change it (so it will be a no-op for the rest of the life cycle). Technically if we merge this PR it will solve a bug, but it will also "change" the behavior of this specific edge case. So where is the line that we draw?

IMO, there will always be bugs and undefined behavior that users will find that we won't be able to catch right away. What we should promise users is that they should only take dependencies on behavior/components that are documented in our API surface. If they take a dependency on a "bug", we should not need to promise them that these will not break. One could argue "well what is a bug and what is a breaking behavior change"? This is why these cases will probably require some judgement on our part as a community. So our official message should be "users should not take dependencies on functionality and behavior that is not documented in our public APIs, but if they do, we do not have a promise that there will be stability guarantees.
Also, Dot net SIG has also taken a similar stance.

With that being said, we should make the experience and transition as smooth as possible for customers. If we are fixing major bugs that causes behavior changes, we should do our best to be as transparent as possible, to allow users time to upgrade and adjust to the change.

This is an important issue to flesh out before our 1.0.0 so please comment on this if you have thoughts.

I agree. Also, from a users perspective, if I take a dependency on a library, I expect it to work and not break my apps (with or without crashes) months or years from now. If updating breaks my apps by introducing exceptions or behavioral change that fundamentally alter how the library functions or the data it produces then I'd consider that a breaking change.

I consider that for practical reasons it may not be convenient to stick to the very strict and limited definition of breaking changes that I suggested. In my opinion, the ideal scenario would be to be able to guarantee the user "you application code won't break when you use a version whose major number is the same as the one you have been using". This is also impossible to do, in my opinion, because application code is outside our control.

What I consider critical from what @lzchen suggests is to only increase the major version number for a behavioral change when the behavioral change makes us introduce a change in documentation. I understand that documentation is in itself a commitment to our users, not as strictly defined as an API but a commitment still.

One really important use case to remember is library authors who instrument their library directly with opentelemetry-api. In their setup.py they will probably put opentelemetry-api~=1.0 to leave a wide range for pip to resolve dependencies on. If we bump to 2.0 in the next few months, it could make a be a big problem for interoperability between libraries.

E.g. libfoo depends on opentelemetry-api~=1.0 and libbar depends on opentelemetry-api~=2.0. This is huge problem because now users can't install those two packages together because we were too hasty doing a major version bump.