semantic versioning of API bundle

Question

When starting with a package versioned at 1.0.0 in an API bundle, what should the new version be after adding a new interface to said package? The whitepaper makes this statement regarding compatibility:

It should be obvious that binary compatibility plays an important role in backward compatibility. However, backward compatibility is also very dependent on the semantics. If the responsibility of an interface changes it could still be binary compatible but no longer be backward compatible.

At the same time...

3.micro — A difference in the micro part does not signal any backward compatibility issue

A new interface does not result in any sort of binary incompatibility for its providers—it is quite possible to simply omit an implementation. Is this considered a "backward-incompatible" change in the semantics of the package? Does this imply the new version should be 1.1.0?

Answer 1

Adding an interface to a package is at least a minor change (1.2.3 -> 1.3.0) since you break the provider of the API (which in OSGi is a package), providers of an API have virtually no backward compatibility since they, well, provide the API. After all, any new obligation in the API requires some new code.

Now assume you put an obligation on the consumer to implement this new interface in the API. This change (not visible to the compiler) obviously breaks all existing consumers and will therefore be a breaking change for everybody (e.g. 1.2.3 -> 2.0.0).

To conclude:

• Micro change -> backward compatible with existing providers and consumers of the API
• Minor change -> existing providers of the API are not compatible but consumers are
• Major change -> existing providers and consumers are no longer compatible

Answer 2

The semantic versioning does mention:

Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API.

The addition of the new interface should be considered semantically backward compatible if it does nothing more than calling several old interfaces, now chained into one new operation.
In which case, a minor version increment is enough.