[cctbxbb] Module versioning (was Re: Debian Package)

[Radostan Riedel]

On Fri, 31. Aug 02:05, Luc Bourhis wrote:
> Right, I am willing to learn! 
Great.
> 
> But before, a comment is in order: what about our Python code? That's a large part of the cctbx and it seems to me the very same reasonings justifying so-versioning applies to Python modules and packages: API's change in incompatible ways on a regular basis. I know many projects do maintain a __version__ string. Is there also some sort of official policy here in the Linux software community? Imho it would be meaningless for the cctbx to invest time in proper so-versioning if we do not version Python because in many instances, a change in the Boost Python interfaces will go hand-in-hand with changes in the Python modules.
I don't think there is anything special about versioning python extensions. It
should be versioned by distutils like the module too. But maybe Baptiste knows more on that.

> 
> Now onto so-versioning per se. I am afraid I find the libtool manual excerpt you quoted totally obscure. If you understand it, could you tell me what the next version number would be if we started with e.g. 1.2.3 and then
> i. change some implementation but not API;
> ii. added new API without touching existing ones;
> iii. removed some API without changing existing ones or adding new ones;
> iv. changed existing API's without deleting any or adding any?
OK lets assume you start versioning you should start with 0.0.0 (current.revision.age)

current
    The number of the current interface exported by the library. A current value of 0, means that you are calling the interface exported by this library interface 0.

revision
    The implementation number of the most recent interface exported by this library. In this case, a revision value of 0 means that this is the first implementation of the interface.
    If the next release of this library exports the same interface, but has a different implementation (perhaps some bugs have been fixed), the revision number will be higher, but current number will be the same. In that case, when given a choice, the library with the highest revision will always be used by the runtime loader.

age
    The number of previous additional interfaces supported by this library. If age were 2, then this library can be linked into executables which were built with a release of this library that exported the current interface number, current, or any of the previous two interfaces.
    By definition age must be less than or equal to current. At the outset, only the first ever interface is implemented, so age can only be 0. 

OK now after the public release (we now have 0.0.0) you are changing any sources 
for this library, the revision number must be incremented. This is a new
revision of the current interface. 0.0.0 ---> 0.1.0

If the interface has changed, then current must be incremented, and revision
reset to 0. This is the first revision of a new interface. 0.1.0 ---> 1.0.0

If the new interface is a superset of the previous interface (that is, if the
previous interface has not been broken by the changes in this new release), then
age must be incremented. This release is backwards compatible with the previous
release. 1.0.0 ---> 2.0.1

If the new interface has removed elements with respect to the previous
interface, then you have broken backward compatibility and age must be reset to
0. This release has a new, but backwards incompatible interface. 2.0.0 ---> 3.0.0

And we always have to keep in mind not to change any numbers during the development but before a public release.
This way the numbers are not growing rapidly.

Hope that's more clear now.

Information found here: http://sources.redhat.com/autobook/autobook/autobook_91.html