Discussion:
[vbox-dev] Two changes in patch releases' API?
Tiago Espinha
2013-12-05 12:03:42 UTC
Permalink
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)?

- 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?

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!

Best,
Tiago
Klaus Espenlaub
2013-12-05 16:21:49 UTC
Permalink
Hi Tiago,
Post by Tiago Espinha
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
- 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.
Post by Tiago Espinha
- 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.
Post by Tiago Espinha
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
Post by Tiago Espinha
Best,
Tiago
Continue reading on narkive:
Loading...