On library and its API versions

Many people still confuse the library version and its API version. This leads to problems like not knowing what APIs are supported and when deprecated API will be removed.

There are lots of unuseful versioning examples out there. I am going to present the most useful and correct one.

The API version needs just one number, that is increased when new API is added to the existing one.

So, for example. we can have our "geometry3" API that has an API version number of 1.
If we add a method area() to our Shape class we increment the API version number to 2. There should not be any problem because old API version1 users will still be able to use all the implemented API.

Also, it is possible to have a library implement various APIs. Like in our example it would be able to implement "geometry2" and "geometry3" to support an easy migration to the new API. After some time of "geometry2" being deprecated it could be removed.

For the library version we just need a number (or date) to be able to differentiate old releases for new ones (and be able to differentiate library files).

So, for example, or library version could be 20080610 and if you look what API versions it implements you would be able to see "geometry2.5" and "geometry3.2".

So when you create a new interface like "geometry4" you start from scratch and can add API from new minor API version to the next, but you must not change or remove API since that would break compatibility from prior minor API version number users.

It is common to just have different binaries that implement each API mayor version like having libgtk-1.2.so.0 and libgtk-x11-2.0.so.0 but you could be able to just have a libgtk that implements both APIs in the same binary. You could also be able to have different binaries implementing the same APIs in that case there is a need to a way to specify what library should provide what interface to your binary, maybe using dependency injection.

So, package managers like APT, should work by having programs depend on API versions like "geometry3.2" and be able to fetch a library package that implements "geometry3.2" or newer like "geometry3.4"