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
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 :/
On Thu, Sep 21, 2017 at 01:20:47PM +0800, Harald Welte 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.
(And then we also have the feeds of built packages. I hope we'll put the first one in place on December 1st, Osmocom CellNet 17.12, to start off the planned schedule of a new feed every three months.)
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.
Ok, thanks for the clarification!
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?
The only way to ensure we don't make mistakes there is to have an automated way that tries to build/link programs against each depending libraries' both beginning and end of the API version it claims to be compatible with.
I remember we mentioned something like this earlier in a release mail thread.
Max asked me to transfer our comments and conclusions to the 'Making a Release' wiki page, and indeed I have gathered a lot of knowledge on it now. I would anyway nitpick around on anything someone else wrote :P
First though I am focusing on remaining openbsc.git split tasks, like the manuals and debian packaging. There's also still loads of dead code to be pruned.
BTW, I feel a bit overloaded at the moment, my attention often drawn away from those urgent topics. I'm also a bit fed up with releng, jenkins, mails and docs and would enjoy some good old hacking for a change :)
Well, anyway, getting on with it... It should be over and mostly done *some* day.
~N
-
Harald Welte -
Neels Hofmeyr