Simplify and document version-info bump up procedure
The following page describes how to bump up library version numbers before a software release with libtool: https://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html
Most of the cases we bump up current
version number to indicate that new Kea must use new library. The major source of confusion was the age
number. This number should be set back to 0 whenever the new library should not be used by the old Kea code to avoid crashes. In libtool terms this is the case when existing interfaces has been changed or removed. The old Kea version could be using those interfaces in the form in which they previously existed leading to crashes.
We recently tried to follow the guidelines in keeping the age
number positive and incremented, rather than set to 0 in cases when the new lib version could work with old Kea version. In libtool terms it is the case when new interfaces were added and existing interfaces were neither changed nor removed. So, the old Kea version is never using new interfaces but that's ok. Since old interfaces are not modified it is safe for old Kea to use them. That's the theory....
The reality is that engineers working on the tickets to bump up lib version numbers often face a dilemma what it means that the interfaces are neither changed nor removed. Well, removed may be more obvious. For changes, the fact that you don't instantly see them doesn't mean they don't exist. Kea is a complex software and there are many dependencies between various modules. We think that we made a mistake several times assuming that no interfaces were changed but the changes took place, only they weren't that obvious.
This ticket is to propose and document some consistent way of using libtool version numbers which would minimize the risk of mistakes.
One of the schemes to be considered is the following:
- if there were any code changes in the library between previous release and current release bump up current version number and set other numbers to 0, i.e. c+1:0:0.
- if there were no code changes in the library, leave the version-info as is.
That way we'd preclude the use of old Kea versions with new Kea libraries versions. We'd also require that new Kea version is always using the most recent code, even if the applied changes were cosmetic. This is a brute force way to keep the libs consistent with the Kea version, which may be considered as a down side, but it also has some advantages besides mistakes avoidance....
One of the benefits of such approach is that it becomes trivial to automate lib version bumps with a script that checks whether there were any changes in the lib and bumps up current number. Previously, an engineer had to look and investigate what class of changes were applied and that's not something the script could do.