[vbox-dev] Two changes in patch releases' API?

[Klaus Espenlaub]

Hi Tiago,

On 05.12.2013 13:03, Tiago Espinha wrote:
> Hi everyone,
>
> I'm doing a study in (web) APIs and the API provided by VirtualBox is
> part of my analysis.
>
> What brings me to this mailing list is two questions where the
> VirtualBox developers can greatly help me with:
> - One of the things I noticed was how Oracle advertises that minor
> version releases can push API changes. Is there a reason for this
> deviation from the more traditional "semantic versioning" where API
> breaking changes are saved for major releases (c.f.
> http://en.wikipedia.org/wiki/Software_versioning#Semantic_versioning)?

It's about what's considered a major and minor version. Even the 
VirtualBox build system is a bit undecided about the terminology (it 
constructs the complete version number as MAJOR.MINOR.PATCH), but we 
always (starting with VirtualBox 1.1 IIRC, in any case many years ago) 
considered the MAJOR.MINOR.0 releases as "major", and the maintenance 
releases for such a major release left the interfaces intact, and this 
means effectively there are no changes possible.

The challenge we're having is that for the plethora of API bindings 
we're offering (C++/C/Python/Perl/Java/..., many in both native API and 
webservice flavors), at least one of them is bound to consider a 
particular change (even harmlessly adding methods!) to be incompatible, 
so the "Semantic versioning" theory quickly collapses under the presence 
of gravity in the real world.

> - Another thing that I noticed was that from version 3.0.0 to 3.0.2 as
> well as from version 4.0.2 to 4.0.4 there were also breaking changes.
> Seeing as these are patch releases, what was the reasoning to push
> these changes? Was there perhaps a security concern? Was it merely an
> overlook where changes were mistakenly pushed to the final release?

I can't really follow what you're referring to with the 4.0.2 to 4.0.4 
changes... there were big changes to the VirtualBox.xidl file which are 
presented in a confusing way by the usual diff utilities, misleadingly 
hinting that the change was bigger than it actually is - it's a giant 
change to the textual descriptions, but no actual incompatible API 
change. All I could find is that a method parameter was renamed for 
better self-descriptiveness, but that's miles away from an incompatible 
change.

The change between 3.0.0 and 3.0.2 was more intrusive, that's true. It 
deleted some not really useful API methods and phased out the "tri-state 
bool" type, replacing it with the standard bool type. Strictly speaking 
that's an incompatible change, but as these methods and the 3rd value 
weren't really useful and thus the probability of breaking existing 3rd 
party code (written in the 10 day window between 3.0.0 and 3.0.2) was 
negligible, we decided it's worth it. The only alternative would've been 
dragging around not really working cases in the API code for months, 
just in case someone relied on them.

> Any help with either of these questions is greatly appreciated!
>
> As a side note, please understand that I'm not trying to point fingers
> but rather trying to understand what was the reason for these two points!

It's the difference between theory and practice... while the 3.0.2 
release was clearly bending the rule, we didn't take this lightly and 
designed the change very carefully to have the least possible impact. It 
was a carefully calculated risk, and time (in the form of complete 
absence of complaints about the change) has fortunately proven us right.

Cheers,
Klaus

>
> Best,
> Tiago