Need better versioning

[Michi Henning]

Currently, we are changing the micro version (the z in x.y.z) when we make an ABI breaking change. This creates problems because there is nothing in the machinery to alert a client of our library when there is a mismatch.

We do have a version check that kicks in when a scope is initialised, but that one only looks at the major version number (the x in x.y.z).

The problem is that we have users outside our team who are using the library while it is in development. To let them know that the ABI has changed, we'd have to change the major version number, but that would mean that we'd be at version 35.y.z before we even have the first official release. And it is not an option to, during development, increase the major version number and then reset it back to 1.0.0 for the release because that runs the risk that, somewhere, and earlier incarnation of 1.0.0 may still be kicking around. After all, the whole point of version numbers is that they are monotonically increasing.

I really would like to change the versioning such that the major version number is used to indicate major milestones or feature additions. To indicate ABI breaking changes, I want to use the minor version. This would allow us to use a sequence such as:

0.1.0 Some release
0.1.1 ABI compatible update
0.2.0 ABI incompatible update
...
0.17.3 Final version before release
1.0.0 First release version, same as 0.17.3, just with different version number.
1.0.1 ABI compatible patch release
1.1.0 ABI incompatible patch release

This will give us a way to indicate to our alpha/beta testers when the ABI breaks, and it provides a clean reset of the version number for releases.

For the .so, instead of having

libunity-scopes.so -> libunity-scopes.so.1
libunity-scopes.so.1 -> libunity-scopes.so.1.0.0

we would have

libunity-scopes.so -> libunity-scopes.so.1.0
libunity-scopes.so.1.0 -> libunity-scopes.so.1.0.0

The version check in the run time would be updated to check both major and minor version for the compatibility test.

None of the above is difficult. I'm not clear on what the wider implications are for debian packaging, testing, CI, and the like though.

But I really would like to make this change. It'll be particularly important after we have released and do "version 2" of the library. How are we going to get new versions of the library to our customers if there is no way to indicate ABI changes other than by changing the major version number? By making the minor version the most significant one for the ABI check, we are in a better position. For example, assuming 1.1.3 is the final released version, for early access testing, we can use 1.20.0 as the starting point for version 2 and then count up from there (1.20.z, 1.21.z, etc.). Then, on release, the new version becomes 2.0.0.

Opinions anyone? James, you are most expert with the debian implications. Can you help here?

[PS Jenkins bot (ps-jenkins)]

Fix committed into lp:unity-scopes-api/devel at revision None, scheduled for release in unity-scopes-api, milestone Unknown

[Marcus Tomlinson (marcustomlinson)]

Fix released into lp:unity-scopes-api at revision 343