search

tukaani-project / xz

XZ Utils
https://tukaani.org/xz/
Other
623 stars 115 forks source link

[question] How is the backward compatibility support for future versions? #132

Closed uilianries closed 3 months ago

uilianries commented 3 months ago

Hello!

We have the xz project packaged in Conan Center and are inclined to support version ranges, so users could install the latest version of xz, but compatible be with older versions too.

The ABI laboratory shows until the version 5.3.1 as backward comparible all previous versions: https://abi-laboratory.pro/?view=timeline&l=xz. I didn't find any explicit mention in the documentation or in other issue.

So, I would like to know if the project follows the same compatibility rule for 5.4.x and any future minor version should be backward compatible?

Larhzu commented 3 months ago

API and ABI of the latest stable release is backward compatible down to 5.0.0 ignoring the development releases (alpha and beta releases). The development releases have had and will have API/ABI additions that don't end up in any stable release.

If an intentional API or ABI breakage occurs in a stable release, the major version will be incremented (XZ Utils 6). While the package has had basic symbol versioning support since 5.2.0, I currently don't plan to use it to avoid ABI bumps. It would be a hassle because it likely would only be usable with glibc.

5.2.0, 5.4.0, and 5.6.0 added new API and ABI symbols. So if an application is built against 5.6.x, it might not run if liblzma is then downgraded to 5.4.x and the application used 5.6.x APIs. If the application didn't use 5.6.x APIs then downgrading to 5.4.x is fine. This is because symbol versioning isn't used to avoid ABI bumps (there are no 5.6.x variants of 5.4.x symbols).

With the xz command line tool, a somewhat significant compatibility change is that 5.6.x uses threaded mode by default. This can affect scripts that haven't taken into account that such a default is possible. However, it was possible to use the XZ_DEFAULT environment variable to enable threading by default with 5.2.x already.

Section 2 in README explains the versioning. In addition to language fixes, that text hasn't changed much since 2008. 694952d545b6cf056547893ced69486eff9ece55 added a sentence in 2011. :-)

The basic docs (README and such) need to be updated at some point, so if you think section 2 should say something it currently doesn't, please tell.

Thanks!

uilianries commented 3 months ago

@Larhzu Thank you for your detailed explanation! I failed to find that information, sorry!