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

Harald Welte laforge at gnumonks.org
Thu Sep 21 05:20:47 UTC 2017


Hi Neels,

On Wed, Sep 20, 2017 at 10:07:55PM +0200, Neels Hofmeyr wrote:
> It seems there are a lot more versionings around than I thought...

Really?  There's basially just the LIBVERSION related to a librrary API
(or actually ABI), and the package version.  And those two have no
relation.

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

correct.

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

ack.

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

Without giving it too much thought: Intuitively it seems strange to tie
the two to each other?

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

yes, that's how you make sure you can install two different 'current'
versions of a given library concurrently, in case you have some programs
requiring an old version (.so.1) and some a new (.so.2) installed
concurrently.

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

ack.

> 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?

I think that's a common misunderstanding, and one that people have to
get over with, we cannot fix common misconceptions about underlying
technology in use in Osmocom.

Just look at any random Debian system:

ii  libavutil52:amd64                                           10:2.3.3-dmo3                          amd64        FFmpeg avutil library - runtime files
ii  libavutil54:amd64                                           10:2.4.1-dmo1                          amd64        FFmpeg avutil library - runtime files
ii  libavutil55:amd64                                           7:3.3.3-4

You can see quite clearly that it's completely normal to have
commonly-used packages that don't follow the "abuse" but have source
code release versions completely independent of library ABI versions.

> 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... :/

I think all of us learn new things all the time, so no worries about
that :)

> Will we have the discipline to bump API current for each addition?

At least this is the plan / expectation.

> And bump each depending projects' debian depends-clauses?

The question to me is: Can we automatize/script this in some way, at
least partially so that it's easy to avoid making mistakes.

I think the most difficult question is on th "application/library-user"
side, i.e. when you use a given function from a particular library: How
do you know in which API/ABI version that given symbol was added?

Alternatively, we could of course simply have a script that *always*
bumps the 'depends' of all our applications every time we bump the API
version on the library.  Not elegant, but would ensure there would never
be any incompatibilities :/

-- 
- Harald Welte <laforge at gnumonks.org>           http://laforge.gnumonks.org/
============================================================================
"Privacy in residential applications is a desirable marketing option."
                                                  (ETSI EN 300 175-7 Ch. A6)



More information about the OpenBSC mailing list