Re: README - confusing, irrelevant, redundant, useless

[Russ Allbery <rra@stanford.edu>]

Ben Armstrong <synrg@sanctuary.nslug.ns.ca> writes:

> While exceptions certainly exist, most of the time, a user reporting a
> bug on a Debian package directly upstream is not appropriate.  It is
> better for the user to first seek help from their distribution.  Then,
> if it is clear that the issue is upstream's problem, take it up with
> them.

I don't disagree with that, but I do strongly disagree with the idea that
this implies we should in some way hide or make less available the
upstream bug reporting address.  It should be available for those cases,
and as a fallback (and also to avoid removing documentation that upstream
may want to see included; some people get touchy about things like this,
and when there isn't a compelling reason to go against their wishes, I'd
rather not see us do so).

> I would further maintain that unless you download, build, install and
> test upstream's package without Debian patches, finding the same bug in
> their own untainted release, you cannot reliably say there is an
> upstream bug.

This depends *greatly* on the sophistication of the bug reporter, and is
certainly not a statement that you can make as a general case.
Particularly for Debian packages that document clearly what changes they
make relative to upstream, it is often quite possible to establish that
the bug is an upstream bug without separately building it from upstream
source.

> So, it's not that the bug-reporting address is useless.  It's that it is
> misleading to suggest to the user that bypassing filing a bug against
> the Debian package and going directly to upstream is recommended.

This part I agree with.  I'm not sure that I agree that shipping the
original upstream README is doing this, though.  (How many Debian users
not sophisticated enough to already grasp these issues actually look in
/usr/share/doc in the first place?)

> If there is a way of presenting this information so that those with a
> legitimate need have easy access to it, while at the same time pointing
> the majority of the users at the Debian Bug Tracking System, then by all
> means, include it.  But I doubt if anyone currently takes the care to
> make this distinction in their packages that include upstream
> bug-reporting addresses.

Well, I for one am certainly reading this thread with an eye to improving
my handling of READMEs in my packages.  But, taking off my prospective DD
hat and putting on my upstream hat for a moment, I very much hope that
people won't take away from this thread the idea that hiding the upstream
bug reporting address is a good idea.  I want the standard bug reporting
information to be available to all users of my packages, including Debian
users.  If someone submits a Debian bug to the regular INN bug reporting
addresses, I'm quite capable of telling them to use the BTS instead or
forwarding the bug to the INN package maintainer or BTS as appropriate
myself.

I can be convinced that the best case is to clearly explain to users when
to use one and when to use the other, and this thread is starting to
convince me that nearly all packages should have a README.Debian file at
the least (if for nothing other than to point users at what commands to
use to get started, as I've often had to resort to dpkg -L as well, and to
say affirmatively that there are no Debian-specific modifications).  But
given the choice between not mentioning the upstream bug reporting address
at all or including it in ways that may be confusing, the latter seems
clearly superior to me.

-- 
Russ Allbery (rra@stanford.edu)             <http://www.eyrie.org/~eagle/>