src/CMakeLists.txt SOVERSION

[pullmoll]

I don't think it's a good idea to set the SOVERSION to major.minor.patchlevel in https://github.com/commonmark/cmark/blob/a5c83d7a426bda38aac838f9815664f6189d3404/src/CMakeLists.txt#L87 The reason is that any project depending on e.g. the libcmark.so.0.28.3 will need to be rebuilt once you update to the next version, even if that is not necessary because there is no ABI change.

IMHO it should be sufficient to use just SOVERSION ${PROJECT_VERSION_MAJOR} because the shared library already carries the full version number of the project.

In the Void Linux template for cmark I currently sed the minor and patch level away to avoid having to rebuild mkvtoolnix for every cmark update :)

[nwellnhof]

I added the patch level to SOVERSION in 2015 (commit https://github.com/commonmark/cmark/commit/130b87d0b0aa0979c3f8bfdb9ff97be7051da370) because back then, the ABI changed with patch level releases a couple of times. The ABI has been mostly stable since then, so I'm OK with removing patch level from SOVERSION.

Major/minor is tied to the version of the Commonmark specification. Some changes to the spec could be considered an API change, so SOVERSION should be bumped with minor releases. Under the current versioning scheme, removing the minor version from SOVERSION also makes it impossible to make API/ABI breaking changes without bumping the major version to 1. As an alternative, it's entirely possible (but slightly confusing) to decouple SOVERSION from the project version. Keeping the same SOVERSION across releases also requires some diligence by the release manager.

So the questions are:

1. Is the spec stable enough so possible future changes can be considered bug fixes more than API changes? This is subjective, of course.

2. Should SOVERSION be decoupled from the project version? We could simply set SOVERSION to 1, 2, 3, ... for future releases whenever there's a breaking change. Backward-incompatible changes always require to bump SOVERSION. For spec changes, it's a judgement call.

3. Can we make sure that the release manager is aware of these issues? Forgetting to bump SOVERSION can cause lots of trouble for downstream projects, especially language bindings that link against the dynamic library.

[pullmoll]

Well, all this is entirely your decisions to take. I know that in many projects the soversion numbers are unrelated to the project version. I guess keeping a major.minor soversion version could work just as well. Cmake creates the intermediary symlinks in that case AFAICT and we, as a project packaging libraries, rely on either major or major.minor versions to track back the source for a specific shared library, i.e. the package name.

For cmark, when a template was first added to our repository, the entry was just libcmark.so.0 and I wanted to keep it that way, which is why I patched the build.

From the view of a packager a major soversion change tells that I definitely need to check if the library is still usable at all and need to check all packages depending on it.

For a minor soversion change I know I need to rebuild dependencies because the API and/or ABI have (or may have) changed.

Changes to the patchlevel of the soversion are usually irrelevant to a packager. They tell to look for other packages linking against the library's static version (*.a), if any, and rebuild them for bugfixes etc.

Any package can of course use any scheme for increasing their version numbers. Increasing the soversion numbers OTOH should in some way or another be related to the API/ABI changes or possible breakage. I believe this is the reason why soversion does not need to be derived from the project version, but may well be, if you decide to use the same reasoning for version number bumps.

[jgm]

+++ Nick Wellnhofer [Jan 18 18 15:21 ]:

So the questions are:

1. Is the spec stable enough so possible future changes can be considered bug fixes more than API changes? This is subjective, of course.

Hard to say at this point. Certain imaginable spec changes would require API changes, and even apart from spec changes, there might be reasons to change the cmark API.

2. Should SOVERSION be decoupled from the project version? We could simply set SOVERSION to 1, 2, 3, ... for future releases whenever there's a breaking change. Backward-incompatible changes always require to bump SOVERSION. For spec changes, it's a judgement call.

That could be a good solution. It would require some attention in creating releases.

Another possibility would be to decouple the cmark version number entirely from the spec version, though I find it useful to have this correlation, at least while we're in 0.x.

[nwellnhof]

Can we reopen this issue? This should be addressed at some point.