Bug#708566: library -dev naming policy encourages unnecessary transitions (was: Re: Upcoming libgd2-{xpm,noxpm}-dev -> libgd2-dev transition)

[Guillem Jover]

Hi!

[ Just saw while drafting this, that you filed the bug on policy, so
sending a copy there too, let's continue the discussion there then. ]

On Wed, 2013-05-15 at 09:51:23 -0700, Russ Allbery wrote:
> Andreas Beckmann <an...@debian.org> writes:
> > On 2013-05-15 09:58, Ondřej Surý wrote:
> >> The '2' in libgd2-dev is from 2.x.x, and not from the SONAME to reflect
> >> the API version (1 vs 2).
>
> > Which is, at least, confusing, as it is different elsewhere. And
> > violates Policy Chapter 8.
>
> Policy is wrong here.
>
> If there are development files associated with a shared library, the
> source package needs to generate a binary development package named
> librarynamesoversion-dev, or if you prefer only to support one
> development version at a time, libraryname-dev.
>
> As written, this requires one to either use a non-versioned -dev package
> or to change the -dev package name with every SONAME change. We do not
> want developers to do the latter. It results in a bunch of unnecessary
> transitions. The -dev package name should only be changed when the API
> actually changes in significant ways and multiple co-installable -dev
> packages are desirable.

Right (and apologies for the bogus advice to rename to libgd3-dev, even if
made as a side comment and regardless of the package needing to be renamed
anyway :), I agree in theory that'd be ideal, but in practice the problem
with this is that it depends on lots of factors that can make the package
names very confusing or generic advice difficult.

Selecting the package name for the shared library just depends on the
present ABI, and it always needs to be changed (on SONAME bumps) to avoid
run-time breakage, and we already do have problems with people getting
that wrong (witness this thread), which is the important one, because it
can make programs not work. Choosing a suboptimal -dev package name might
imply FTBFS, and as such more work, but I'd posit that's better than a
broken run-time; also the -dev package name depends on fuzzy stuff like:

* are the API changes small enough that they do not warrant a different
name to avoid breaking non-switched packages, or what it breaks
deserves to be broken anyway (ex. hidden gets() from latest glibc).
* are there many reverse-dependencies, that an API change regardless
of size might render lots of packages unbuildable.
* does upstream have a sane project versioning so that the -dev package
can use that as a base, or would the packager need to invent something
completely unrelated (which might also be confusing for API users),
or use something unwieldy like the full version because upstream
breaks API on minor revisions. Lots of projects conflate the API and
ABI with a single version, some others might not even have a version
that denotes the API of a shared library that might be a tiny part of
a bigger project with many components.
* are API changes so common, that we might end up with shared
libraries and -dev packages sharing the same version but being
unrelated on the archive, which can be quite confusing?
Say liba1-dev → liba3 and liba3-dev → liba5.
* if API breakage is pretty uncommon and we don't foresee big future
changes then unversioned -dev is usually best, but we might get
suddenly surprised; altought we can always switch to version the
-dev, this might be difficult to predict.
* possibly others...

> I wonder if this Policy wording is what's caused several ill-advised -dev
> package renamings.

Perhaps, but I think we just lack better documentation and advice when
it comes to shared library handling in general.

There was an attempt by Junichi Uekawa (CCed) some time ago [L], but
AFAIR some people shunned it because supposedly it contained inaccuracies
or suboptimal advice (I've to confess I never reviewed it). IMO these
should have been corrected instead of trying to banish it from Debian.
I think something like that should be revived, reviewed and subsumed
into the policy manual or the devref.

[L] <http://www.netfort.gr.jp/~dancer/column/libpkg-guide/libpkg-guide.html>

> I'll file a bug against Policy.

That'd be wonderful (ok seen now :).

> I'm not sure what we *do* want to say. I'm inclined to say that the
> version in the -dev package name should be some meaningful version chosen
> by the packager (possibly based on the upstream version) that will change
> when the API changes in such a way as to make multiple -dev packages
> desirable. But we can talk it over in the Policy bug.

The advantage of “either libNAME-dev or libNAMESOVER-dev” is that it's
pretty straightforward and simple, so less error prone, and I guess if
most upstreams usually break API when breaking ABI, it tends to be more
“correct” than not, it can still be suboptimal though if using the
libNAMESOVER-dev form unnecessarily. (I think breaking API w/o breaking
ABI is pretty rare, possibly restricted mostly to projects using full
versioned symbols support, like glibc.)

Of course a project can break ABI w/o breaking API; in C for example
by shuffling struct members, or changing variable types, etc, but is
that as common as breaking both?

> > [Another interesting case where SOVERSION does not match VERSION is the
> > (correctly named) package pair libtiff4 and libtiff5, built from tiff3
> > (3.x) and tiff (4.x)]
>
> I have another pair myself (libsaml2-dev and libsaml7), and I don't
> believe that naming wrong, although I could be convinced otherwise.

Nah, I think that's actually a very good example of proper version
handling, because the project version is 2.x.y, and the API seems to be
pretty well defined with a spec versioned as 2.0. I'm not sure that's
common though?

Thanks,
Guillem


--
To UNSUBSCRIBE, email to debian-bugs-...@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listm...@lists.debian.org

[Russ Allbery]

Guillem Jover <gui...@debian.org> writes:

> Perhaps, but I think we just lack better documentation and advice when
> it comes to shared library handling in general.

> There was an attempt by Junichi Uekawa (CCed) some time ago [L], but
> AFAIR some people shunned it because supposedly it contained inaccuracies
> or suboptimal advice (I've to confess I never reviewed it). IMO these
> should have been corrected instead of trying to banish it from Debian.
> I think something like that should be revived, reviewed and subsumed
> into the policy manual or the devref.

> [L] <http://www.netfort.gr.jp/~dancer/column/libpkg-guide/libpkg-guide.html>

I'm wholeheartedly in favor of this, and even had some thoughts from time
to time about helping with (or adopting) that guide and rolling it into
Policy. But I haven't been doing a very good job finding time for Debian
things lately. I'd love to see someone take this on.

--
Russ Allbery (r...@debian.org) <http://www.eyrie.org/~eagle/>

[Charles Plessy]

Le Mon, May 20, 2013 at 07:33:43PM -0700, Russ Allbery a �crit :

> Guillem Jover <gui...@debian.org> writes:
>
> > Perhaps, but I think we just lack better documentation and advice when
> > it comes to shared library handling in general.
>
> > There was an attempt by Junichi Uekawa (CCed) some time ago [L], but
> > AFAIR some people shunned it because supposedly it contained inaccuracies
> > or suboptimal advice (I've to confess I never reviewed it). IMO these
> > should have been corrected instead of trying to banish it from Debian.
> > I think something like that should be revived, reviewed and subsumed
> > into the policy manual or the devref.
>
> > [L] <http://www.netfort.gr.jp/~dancer/column/libpkg-guide/libpkg-guide.html>
>
> I'm wholeheartedly in favor of this, and even had some thoughts from time
> to time about helping with (or adopting) that guide and rolling it into
> Policy. But I haven't been doing a very good job finding time for Debian
> things lately. I'd love to see someone take this on.

Hi all,

in addition, for those who might be discouraged by the difference of format
(Policy in debiandoc, library guide in DocBook), we plan to convert the policy
to DocBook, I hope within this release cycle.

(The Developers Reference is already in DocBook)

Cheers,

--
Charles Plessy
Tsurumi, Kanagawa, Japan

[Junichi Uekawa]

Hi,

At Mon, 20 May 2013 19:33:43 -0700,

Russ Allbery wrote:
>
> Guillem Jover <gui...@debian.org> writes:
>
> > Perhaps, but I think we just lack better documentation and advice when
> > it comes to shared library handling in general.
>
> > There was an attempt by Junichi Uekawa (CCed) some time ago [L], but
> > AFAIR some people shunned it because supposedly it contained inaccuracies
> > or suboptimal advice (I've to confess I never reviewed it). IMO these
> > should have been corrected instead of trying to banish it from Debian.
> > I think something like that should be revived, reviewed and subsumed
> > into the policy manual or the devref.
>
> > [L] <http://www.netfort.gr.jp/~dancer/column/libpkg-guide/libpkg-guide.html>
>
> I'm wholeheartedly in favor of this, and even had some thoughts from time
> to time about helping with (or adopting) that guide and rolling it into
> Policy. But I haven't been doing a very good job finding time for Debian
> things lately. I'd love to see someone take this on.

Some preconditions from that time has changed, and major change since
then has been that binary-only uploads are much easier
infrastructure-wise than before that there's less reason to rename a
-dev package than when this was authored about 8 years ago.

The last time I seriously worked on this document was 2006 and in the
hindsight, I was learning this stuff as I wrote this document, there
must be inaccuracies. But I lack the motivation to revise this
document now.