OSGi Semantic Versioning: Getting There

The recent OSGi Alliance Semantic Versioning whitepaper goes an important step towards really useful versioning.

In my PhD thesis on Specification-Based Component Substitutability and Revision Identification some 7 years ago I noted that component version data should have a well-defined meaning (semantics) so that automated agents can use it in their reasoning about components. The OSGi Alliance whitepaper gets a good way towards this goal.

After having worked in the area for some years, I nevertheless feel that it may not achieve its full effects. Here are two reasons why.

1. API vs Implementation

The paper is very clear about the distinction between API and implementation, and emphasizes that it is a crucial point. Shouldn’t it then be somehow enforced on the package level, e.g. by mandating that API package can only contain interfaces (classes will be ignored)? See Hargrave+Krien’s best practices talk for the discussion. Without similar rules, API versioning policies will be hard to enforce.

2. Status and Strength

Which takes me to the most important point: what is the relationship of this whitepaper and the official spec, what is its “legal status”? Suggestion? Recommended best practice? Proposed required policy? The 4.2 spec still says “Version ranges encode the assumptions about compatibility. This specification does not define any compatibility policy; the policy decision is left to the importer that specifies a version range.”

If the rules set forth in the whitepaper become part of the standard, then it would make more sense to me. Or, if there was a mechanism on the standard level providing indication that these rules are being observed by the given bundle (Bundle-VersioningProfile: semantic-versioning-1.0 declaration?) that the framework could depend on.