Library versioning?

Are we settling for semantic versioning?

What else is there?

How should we prepare to break library ABI, a.k.a major version bumps?

Yes, I know. When we declare the library ABI stable, we do not want to break it lightly again, if at all possible. However, I do wonder if we get enough use to verify the ABI is future-proof before we declare it stable the first time. Having a plan how to do breaking changes to the ABI before we need to do that is reasonable contingency planning and risk management to me. It also means it is easier to decide when people should be starting to rely on libdisplay-info, and also gives library users some assurance of what to expect.

Do we do the libtool thing? I'm still not sure I understand how that works to allow multiple major versions installed in parallel.

Do we do the libweston thing, where the major version is baked into the library name, both DSO and pkg-config, etc.? See https://ometer.com/parallel.html and https://apr.apache.org/versioning.html .

Do we care about building against recent library but still supporting running on older library?

This is within the same major version, of course.

For example, Waffle seems to be allowing this, see waffle.h:

It encloses new API additions in #if WAFFLE_API_VERSION >= 0x0106 .. #endif in the headers.

It also handles deprecation:

#if WAFFLE_API_VERSION >= 0x0107
#    define WAFFLE_DEPRECATED_1_07 WAFFLE_DEPRECATED
#else
#    define WAFFLE_DEPRECATED_1_07
#endif

The expectation is that the user of the library will #define the WAFFLE_API_VERSION it targets before #includeing any of the library headers. Then, even if the user project is built against a more recent library, the new symbols are not declared, so catching their accidental use is easy. Also, deprecation warnings don't trigger unless the user project targets a version where the deprecation appeared.

This scheme is actually documented for libweston, but we never really implemented it yet, because libweston is still bumping major version every release.