ABI stability policy

[nwellnhof]

The addition of the options parameter to cmark_markdown_to_html in version 0.18.2 breaks the API and ABI. Since the soname of libcmark is currently based on major and minor version (0.18), this can cause problems. If someone updates the libcmark binary from 0.18.1 to 0.18.2, any code compiled against the old version will call cmark_markdown_to_html without an options argument. There won't be a linker error because the soname matches.

We should make sure to always bump the library's soname if the ABI changes. I can see the following solutions:

1. Derive soname from major and minor version like we do now. Only allow ABI changes if we release a new minor version.
2. Derive soname from major, minor and patchlevel. This means to recompile all dependent binaries whenever a new libcmark version is installed, even if it were ABI-compatible.
3. Manage soname manually. Check if there's an incompatible ABI change when cutting a release. If yes, bump soname.

The second approach puts the least burden on the release manager and, at least for now, shouldn't be too annoying for users.

[jgm]

Apologies, I hadn't thought about this. Since we're currently pegging major [EDIT: minor] to the spec version, option 1 is a bit constraining. So maybe option 2 is best for now. We can change back when we stabilize the spec and libcmark. Do you want to make this change?

+++ Nick Wellnhofer [Mar 31 15 03:32 ]:

The addition of the options parameter to cmark_markdown_to_html in version 0.18.2 breaks the API and ABI. Since the soname of libcmark is currently based on major and minor version (0.18), this can cause problems. If someone updates the libcmark binary from 0.18.1 to 0.18.2, any code compiled against the old version will call cmark_markdown_to_html without an options argument. There won't be a linker error because the soname matches.

We should make sure to always bump the library's soname if the ABI changes. I can see the following solutions:

1. Derive soname from major and minor version like we do now. Only allow ABI changes if we release a new minor version.
2. Derive soname from major, minor and patchlevel. This means to recompile all dependent binaries whenever a new libcmark version is installed, even if it were ABI-compatible.
3. Manage soname manually. Check if there's an incompatible ABI change when cutting a release. If yes, bump soname.

The second approach puts the least burden on the release manager and, at least for now, shouldn't be too annoying for users.

---

Reply to this email directly or view it on GitHub:
#23

[nwellnhof]

See pull request #25.

[jgm]

Thanks for the PR (merged). Do you think we should release 0.18.3 now with this change?
Or can it wait?

[nwellnhof]

If it isn't too much work, it would be nice to make a new release.

[jgm]

Will do.