API versions vs. release versions

It seems there are a lot more versionings around than I thought... I am currently deciding on how we want to handle libtool API versions. These are strings of the form current:revision_of_current:compat_age MGCP_LIBVERSION=5:23:4 means that - We are in API version 5. - This is the 23rd "small internal" modification of 5. - We are backwards compatible to 4 previous API versions (1 thru 5). This is not at all related to release versions of the major.minor.patch form. For example, each small tweak of the code will bump the middle 'revision_of_current' number, whether it's a minor or patch release bump. Now I had the plan to actually coincide the major release version with the API current version. When we are in release 1.0.1 thru 1.23.42 and so forth, keep the library API current version at 1. Once we do a major version bump to 2.0.0, we can go on to API current version 2. Coinciding seems to make sense because we anyway don't want to make API breaking changes unless we bump the major release number. BTW the API 'current' version number also appears in the debian package names like libosmo-mgcp2.deb and the installed library files, like libosmo-mgcp.so.2... Keeping the API current the same as release major makes sense to me, but only up to this point: when we add a new side feature to a library. When all of the library stays the same and is backwards compatible, and all we do is add a new function to it, someone linking against it may want to make sure that this new function is included in the installed version. So even if we don't bump a major release, don't break API and so forth, we may still want to increase the API-current version and bump the names of the debian packages as well as installed .so files. Why? Because if we had libosmo-mgcp1 and added function mgcp_frobnicate(), and we want to use mgcp_frobnicate() in osmo-msc.deb, we want to depend on a libosmo-mgcp that has it added, i.e. we bump to libosmo-mgcp2.deb and depend on that from osmo-msc.deb. All the while libosmo-mgcp's version tag still remains at 1.0.23, only the API version changed. This would be the libtool-intended way, and we'd see a lot of debian package names' numbers bumping, not at all related to our major-release, whenever we add any new function to our API. Only in reality, if I see libosmo-mgcp5.deb, as a user I do expect it to be libosmo-mgcp release 5.2.3, not release 1.0.23. Right?? Is that only me? According to libtool, coinciding the API version with the release version is abuse. OTOH it's what I actually expected for most of my life... :/ Will we have the discipline to bump API current for each addition? And bump each depending projects' debian depends-clauses? What do you guys think about this? See https://www.gnu.org/software/libtool/manual/html_node/Updating-version-info… Thanks! ~N -- - Neels Hofmeyr <nhofmeyr(a)sysmocom.de> http://www.sysmocom.de/ ======================================================================= * sysmocom - systems for mobile communications GmbH * Alt-Moabit 93 * 10559 Berlin, Germany * Sitz / Registered office: Berlin, HRB 134158 B * Geschäftsführer / Managing Directors: Harald Welte