[vbox-dev] Two changes in patch releases' API?
klaus.espenlaub at oracle.com
Thu Dec 5 16:21:49 UTC 2013
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.
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
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.
More information about the vbox-dev