API versions vs. release versions

This is merely a historical archive of years 2008-2021, before the migration to mailman3.

A maintained and still updated list archive can be found at https://lists.osmocom.org/hyperkitty/list/OpenBSC@lists.osmocom.org/.

Neels Hofmeyr nhofmeyr at sysmocom.de
Wed Sep 20 20:07:55 UTC 2017


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.html

Thanks!

~N

-- 
- Neels Hofmeyr <nhofmeyr at 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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: Digital signature
URL: <http://lists.osmocom.org/pipermail/openbsc/attachments/20170920/c2bb6300/attachment.bin>


More information about the OpenBSC mailing list