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

[Jonathan Marsden]

Matthew Talbert wrote:

> Newbie sort of question here. According to the page referenced, 
> couldn't the package name be libsword-1.5.11 and SONAME 
> libsword-1.5.11.so ?

Well, sort of yes (you'd need the number in the name, before the dash),
but I think then it is very obvious that libsword falls into the
category of being unstable, in 5.2.2 of the guide:

"The upstream authors have the liberty of choosing two major methods for
versioning using libtool. -version-info, and -release. -release is used
for unstable libraries that change ABI on every new release. However,
such unstable library package usually don't belong in Debian, because it
will require a rebuild in every dependent package against the new
library package."

I suspect that submitting a library package that did the
"libsword1.5.11" or "libsword1511" type of thing could just lead to it
being rejected for this reason, and so it wouldn't get into Debian at
all.  The standards for Debian packaging have evolved slowly over more
than a decade; I think it's best not to fight them.  We need Debian more
than Debian needs us!

I did find *six* library packages with an obvious three-part x.y.z style
version number in their names on my desktop (Ubuntu 8.10 amd86) here,
-- but I think that is the exception that proves the rule, or something;
 six out of over 700 is less than one percent.

> Just going off memory, I think libsword breaks ABI and perhaps API
> compatibility on minor releases (eg, 1.5.9, 1.5.10, 1.5.11 all being
> incompatible).

Which seems to qualify it as being an unstable library, not really
suitable for inclusion in Debian... we'd better hope no-one calls us out
on that.

> So it would make sense to me that the package name
> could be libsword-1.5.11 so it could co-exist with libsword-1.5.9.
> Please let me know if I'm misunderstanding.

Note that the current binary package name portion is not libsword, but
is libsword6 (libsword6-1.5.9-8.1ubuntu1 in Ubuntu Intrepid, for
example!), the next one would be libsword7.  Number before the dash, so
that it is part of the name.  Different package names, so they can coexist.

Incidentally, if you run a Debian or Ubuntu machine and have the
devscripts package installed, you can run

  rmadison -u ubuntu libsword6

and

  rmadison -u debian libsword6

to see exactly what version of that package is in which distributions.
Omitting the '-u ubuntu' or '-u debian' assumes the correct default for
the OS you are running rmadison on, as you might expect.

> As an alternative, could we use libsword11 rather than libsword7?

Maybe, but why would we want to do that?  What problem does it solve?
As I understand it: The current SONAME version-info number in Daniel's
official Debian / Ubuntu packages is 6, so the next one will be 7.  You
just always increment them (by one!), there is no reason to "waste
numbers" really.  If you try to match just the minor part of the package
version, you'd have issues when upstream releases (for example) 1.6.0,
and you can't possibly match any of those because you are already at 11...

If there is an experienced DD or DM on this list laughing at my relative
newcomer (to Debian, not to Linux and Unix) explanations, or if I got
anything significantly wrong here... speak up, please!

Jonathan