Re: [boost] Boost version meaning

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