Subject: Re: [boost] Boost version meaning
From: Andreas Masur (amasur_at_[hidden])
Date: 2008-11-24 21:39:30
On Nov 24, 2008, at 12:16 PM, vicente.botet wrote:
> ----- Original Message -----
> From: "Andreas Masur" <amasur_at_[hidden]>
> To: <boost_at_[hidden]>
> Cc: <boost-users_at_[hidden]>
> Sent: Monday, November 24, 2008 4:04 PM
> Subject: Re: [boost] Boost version meaning
>
>
>>
>>
>> On Nov 23, 2008, at 3:44 PM, vicente.botet wrote:
>>
>>> If we were to version individual Boost libraries which will be the
>>> apropiated schema? Should all the libraries follow the same schema?
>>> What do you think of?
>>> X: complete rewriten or incompatible evolution
>>> Y: new functions or major bugs corrections
>>> Z: minor bugs corrections
>>
>> Well...certainly any version scheme is adequate as long as everyone
>> follows it accordingly which is the main concern in my eyes. Having
>> said that, why not use the (common) version scheme open source
>> projects tend to use. A good example (as well as description) can be
>> found on the Apache APR site (http://apr.apache.org/versioning.html).
>
> Hi,
> Thanks for your pointer. This one is much more oriented to C and
> binary libraries not to C++ header only libraries. Do you think that
> it can be adapted to C++?
> Have you other C++ OpenSource pointers?
Vicente,
of the top of my head....Eclipse uses such an approach (they call it
major/minor/service). There are many other projects that uses a
similar x.y.z approach - granted not necessarily many of them are
header only libraries. STLport is one that comes to mind in this area.
However, I have to admit that I did not study all of the developer
documentation in order to get an understanding whether they actually
follow the same principle at such a detailed level or just happen to
use the common notation of 'x.y.z'.
There are many arguments for and against any given versioning scheme
and I guess everybody understands there is not a perfect one. I have
looked at the whole area when trying to establish a common versioning
scheme for our company. I ended up with pretty much adapting the
'x.y.z' scheme (major/minor/patch in my case).
The problem is simply to define when to increase what. I have defined
a major increase whenever the interface and/or the functionality has
changed in a way that makes it incompatible from the previous version.
For example, a function that used to return a simple integer now
returns an iterator. If a function/interface is extended in a way that
provides backward compatibility (e.g. new function arguments are added
at the end of the parameter list with default values/only new
functions are added), the major number remains untouched.
A minor increase takes place whenever the functionality is extended,
modified or otherwise changed without breaking the interface. A
requirement here is that you can compile your existing code against
the new header/library *without* the need to modify anything.
Finally....an increase of the patch level takes place whenever a bug
has been fixed. I tend to not make any difference between a major or
minor bug since this usually opens the door for lengthy discussions
about what defines either bug. Now....there is however one scenario
where this actually gets a little bit complicated...in the case of
having a bug that requires an interface and/or a functionality change.
In this case, the major number should be increased even though it is
*just* a bug fix.
Looking at this, it pretty much goes along with your suggested
scheme....except for some minor modifications which in my eyes
clarifies some aspects of your scheme. And just with software, the
KISS approach also helps with versioning in my eyes. I certainly don't
want to insult anybody on this list (who am I to judge the experts
developing for Boost) however, it is my belief that a simple, easy to
understand and follow versioning scheme has a much better chance to
get accepted.
So....to answer your question more directly....yes, I think that the
above can be applied to C++ and header-only libraries for the simple
fact that it strips off specific wording in terms of e.g. binary or
source-code compatibility. It pretty much comes down to:
* If you break the interface/functionality, increase the major number
* If you extend the interface/functionality without breaking it,
increase the minor number
* If you just fix a bug, increase the patch level
Given these three *rules*, you can pretty much cover nearly - if not
all - situations you may run into. It probably could worded a little
bit better, but in general it should also be easy and simple enough to
be understood by every developer. It certainly has served me well for
the past couple of years....
Finally....this post has become longer than anticipated....being new
to the list, I hope I did not bother too many of you guys...
Ciao, Andreas