Bug#708566: library -dev naming policy encourages unnecessary transitions (was: Re: Upcoming libgd2-{xpm,noxpm}-dev -> libgd2-dev transition)
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 <anbe@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
Reply to: