[debhelper-devel] Bug#811491: --link-doc Was: [Pkg-freeipmi-devel] Bug#829085: freeipmi: not binNMU safe

[Yaroslav Halchenko]

Thank you Vincent for attending to freeipmi package!

Here is my exploration of the issue: I was a bit bedazzled since original setup
just closely followed established practice, e.g. see
https://wiki.debian.org/binNMU according to which +b1 suffix should be stripped
when establishing value of the ${source:Version} variable, thus rendering
package perfectly binNMUable  (theoretically ;) )

So it is indeed --link-doc which causes the trouble:

        if (package_arch($package) ne package_arch($dh{LINK_DOC})) {
            if (compat(9)) {
                warning("WARNING: --link-doc between architecture all and not all packages breaks binNMUs");
            } else {
                error("--link-doc not allowed between ${package} and $dh{LINK_DOC} (one is arch:all and the other not)");
            }
        }
        # Make sure that the parent directory exists.
        if (! -d "$tmp/usr/share/doc" && ! -l "$tmp/usr/share/doc") {
            install_dir("$tmp/usr/share/doc");
        }
        # Create symlink to another documentation directory if
        # necessary.
        if (! -d "$tmp/usr/share/doc/$package" &&
            ! -l "$tmp/usr/share/doc/$package") {
            doit("ln", "-sf", $dh{LINK_DOC}, "$tmp/usr/share/doc/$package");
            # Policy says that if you make your documentation
            # directory a symlink, then you have to depend on
            # the target.
            addsubstvar($package, 'misc:Depends', "$dh{LINK_DOC} (= \${binary:Version})");
        }


and there is an issue https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=811491  
to which I am following up here as well (CCed that bug report + involved parties):

On Wed, 20 Jan 2016 07:18:59 +0000 Niels Thykier <niels at thykier.net> wrote:

> > arch:all to arch:any - generates >= source:Version depends to binNMUability is 
> > preserved

> Personally I do /not/ consider this case policy compliant, nor do I
> believe it /can/ be (with the correct wording of the policy).  In this
> case, you can (in theory) end up with a case (using partial upgrades)
> where the copyright file of the arch:any does not match that of the
> arch:all.
>   But since the arch:all link-docs, then we now provide incorrect
> copyright information about the arch:all package.

Why not just as binNMU instructions say and have

addsubstvar($package, 'misc:Depends', "$dh{LINK_DOC} (= \${source:Version})");

(instead of proposed >= relationship)?  i.e. just replacing
binary:Version  with source:Version which would strip off +bX suffix (if I got
its purpose correct).  Since critical files such as copyright and
changelog.Debian are not binary specific, and theoretically none of the
documentations is binary specific (as claimed by any -> all dependency), I do
not see any problem with such as resolution...

Thank you in advance for your consideration

> Even if you were to add an upper bound, I can still (theoretically)
> create new (non-binNMU) versions that satisfies the relations.

FWIW theory is a powerful thing, but empirical science is plowing is way
through these days ;):

$> dpkg --compare-versions 2.4-1 lt 2.4-1+b1 && echo yes || echo no 
yes
$> dpkg --compare-versions 2.4-1+b1 lt 2.4-1.0~ && echo yes || echo no 
yes
$> dpkg --compare-versions 2.4-1+1 lt 2.4-1.0~ && echo yes || echo no 
yes
$> dpkg --compare-versions 2.4-1.1 lt 2.4-1.0~ && echo yes || echo no 
no

so I don't see so far how in common use-cases non-binNMU pkg could break
through the ceiling with .0~ suffix

so, theoretically, IMHO --link-docs should follow the binNMU recommendations
and have provided the differential handling for the obscure case that docs are
coming from arch: any pkg while package with a symlink is of arch all.  And ATM
it doesn't, and does break binNMUs.  Fixes at the level of individual
packages (such as was kindly done for freeipmi) are just inappropriate.

My perl foo is non-existent but if you like I could take a shot at improving
the patch slightly if you see my recommendation (which is just to follow
binNMU recommendations) to be the way to go.

> > arch:any to arch:all (no idea if this actually happens or not):

> > For compat 9 or less: Prints warning and does generates nothing
> > For compat 10: errors out the build

> This case can be done correctly by using (= ${source:Version}).  I was
> hoping this was more common than the previous case.

oops -- I guess I took also the wrong way of meaning of "to" all around.
So we seems to be on the same page ;)

-- 
Yaroslav O. Halchenko
Center for Open Neuroscience     http://centerforopenneuroscience.org
Dartmouth College, 419 Moore Hall, Hinman Box 6207, Hanover, NH 03755
Phone: +1 (603) 646-9834                       Fax: +1 (603) 646-1419
WWW:   http://www.linkedin.com/in/yarik