Bug#962710: libedit2: undocumented change to upstream's SONAME

[Simon McVittie]

Package: libedit2
Version: 3.1-20191231-1
Severity: normal

While working with the Steam Runtime, a partial library stack for
third-party binary software, I noticed that ldconfig considers modern
Debian's libedit2 3.x to be older than libedit2 2.x. If both are in the
library search path, this results in 2.x being selected in preference
to 3.x, breaking binaries that expect the full ABI of 3.x.

Investigating this led me to
https://salsa.debian.org/debian/libedit/-/blob/master/debian/patches/update-soname.diff
which changes the SONAME from upstream's libedit.so.0 to a Debian-specific
libedit.so.2, without documenting why. The reason also doesn't seem to
be documented in d/changelog.

Looking back through the git history, it seems that the reason is: back in
2013, at the transition from 2.x to 3.x, upstream switched from a
pmake-based build system to Autotools, and the SONAME moved from
libedit.so.2 to libedit.so.0 at this point. To avoid needing to rebuild
existing libedit-dependent projects, the Debian package started patching
the build system.

The version comparison order problem that I noticed is because the Steam
Runtime (Ubuntu 12.04-derived) libedit.so.2 version 2.11 is implemented
by libedit.so.2.11, whereas modern Debian's libedit.so.2 version 3.x
is implemented by libedit.so.2.0.63, which compares less than 2.11 in
strverscmp() order.

Debian-specific SONAMEs are a problematic pattern: we used to have
more tolerance for them than we do now, but these days I believe it
is considered best-practice for SONAME changes (and ABI management
in general) to happen "upstream first". For example, libcurl diverged
from its upstream in 2007 and only reconverged in 2018, with a lot of
confusion in between (see #858398 for some history), while libpcre 3.x
is still diverged and periodically causing confusion.

Whatever else happens or doesn't happen, if the libedit.so.0 SONAME is
not used, it would be very helpful for the packaging to document why
this happened, perhaps in https://dep-team.pages.debian.net/deps/dep3/
format.

Ideally, I think libedit should transition to its upstream SONAME,
libedit.so.0 (which is how it is shipped in non-Debian-derived
distributions), in a new libedit0 binary package. This would be a
transition which would need to be coordinated with the release team,
but would make future Debian releases more compatible with the rest
of the GNU/Linux world. Because the actual symbols exported are the
same as upstream's, this could be made a "soft" transition by having a
transitional libedit2 package containing a symbolic link
libedit.so.2 -> libedit.so.0, if desired: that way, newly-compiled
packages would depend on libedit0, but existing binary packages that have
DT_NEEDED: libedit.so.2 and Depends: libedit2 would continue to work.

The next best thing, if the libedit.so.0 name is unsuitable for some
reason that I'm not seeing, would be to use an obviously-Debian-specific
SONAME, for example libedit.so.2d. Again, that would be a transition
that would need to be coordinated, but could have a transitional package
to make it a "soft" transition.

The best option that I can see to reinstate the "newer-than" property
(from ldconfig's perspective) *without* a transition would be to
increase the minor (second) version in the name of the library, for
example by bumping both the libtool "current" and "age" fields. Setting
the libtool current:revision:age to, for example, 102:63:100 would
result in libedit.so.2 -> libedit.so.2.100.63, which compares newer
than libedit.so.2.11. The choice of 100 here is entirely arbitrary, and
something like 31 or 3001000 that suggests the version number would be
equally valid.

Thanks,
    smcv