[Pkg-crosswire-devel] API/ABI compatibility, and choice of SONAME for libsword

[Jonathan Marsden]

Matthew Talbert wrote:

> I am a Ubuntu fan and a GnomeSword developer. I *really* would like to
> see updated packages for libsword and gnomesword in the debian/ubuntu
> repos. I know very little about packaging, so I am signed up to help
> move this forward in whatever other way I can.

Cool!  Here are a few questions for the upstream developers I'd be
interested in the answers to, as we ramp up here:

(1) Can you confirm Refdoc's comment that there is significant new
functionality in the sword-1.5.11 libraries compared to 1.5.9?  Can we
get any documentation on what has been added and changed in what library
version, from the perspective of an application developer using the library?

(2) Can we get confirmation as to whether the ABI or API has changed
incompatibly since 1.5.9?  In other words, per the Debian Library
Packaging Guide ( see
http://www.netfort.gr.jp/~dancer/column/libpkg-guide/libpkg-guide.html )
, do we need to bump the SONAME and create libsword7 from 1.5.11 ?  I'm
guessing yes, but we should be able to do better than guess :)

(3) More generally, how are interested parties (like us!) supposed to
find out this kind of version (in)compatibility information among
upstream sword library releases as development of those libraries
continues?  The upstream tarball contains a changelog, but that does not
seem to me to clearly distinguish between straightforward bug fixes and
more significant changes that break compatibility of either ABI or API.

(4) Going even further... Section 5.1 of that Guide says (tongue in
cheek, and perhaps almost arrogantly):

"In most cases, if a package version matches the SONAME, it is a sign
that there is a problem with the versioning scheme. Scrap it, and bash
the upstream with the libtool manual. It is usually a good sign that
either he has not read the manual thoroughly, or he has not understood
it, or both."

I'm no expert on library packaging and libtool, but it looks to me as
though sword currently qualifies for this approach (!), since in the
upstream original lib/Makefile.am we currently see:

libsword_la_LDFLAGS = -release $(VERSION)

and this has to be patched out ("scrapped" to use the language of the
Guide!) in the Debian and Ubuntu packages (currently patched by
debian/patches/02_libver.diff ).

Can someone please confirm that I am understanding this correctly?  If
so, what might it take to persuade the upstream library developers to
reconsider this "SONAME version == package version" approach?  Can we
begin that discussion with them, either here on on sword-devel?  Or
should that kind of discussion wait a while longer (is there past
history on this issue that I am unaware of)?

> For several reasons, I think this list would be better than using the
> sword-devel list.

OK, I'm a newcomer and will defer to your judgement on that!  BTW, if
you can do anything to speed approval of my subscription to sword-devel,
that would be good (I'll probably listen for a while before I say too
much there!); it seems to be awaiting human intervention at this point.

Thanks,

Jonathan