Re: New README.source documentation for Debian packages
Am Montag, den 28.04.2008, 16:13 -0700 schrieb Russ Allbery:
> After extensive discussion in Bug#250202 and elsewhere on how to handle
> the increasing variety of different build and patch systems in Debian, the
> consensus on the debian-policy list is to recommend adding a new
> documentation file, debian/README.source, to any Debian source package
> with a complex build system. The precise definition of "complex" is a
> package where one one cannot unpack the source package with dpkg-source -x
> and immediately get the source that would be built without running further
> commands or where additional steps must be taken to incorporate changes
> beyond just modifying files.
> This package uses quilt to manage all modifications to the upstream
> source. Changes are stored in the source package as diffs in
> debian/patches and applied during the build.
> To get the fully patched source after unpacking the source package, cd to
> the root level of the source package and run:
> quilt push -a
This is some kind of stupid! You expect every package, that uses quilt
or dpatch to ship the same quilt/dpatch documentation? Why doesn't a
short howto shipped with _dpatch_ or _quilt_ doesn't fulfill the
approach , that you need to ship the same documentation with hundreds
or thousands of packages (I don't remember the exact count of packages
I'm sorry, but are you kidding me?
Even the approach to create templates to let people just copy the file
leads me to the same solution: Simply ship these file with dpatch or
quilt (or the other systems) and not with the package sources.
README.source should only contain things, you *cannot* expect from the
tools used. I mean, I understand if you don't want to read long
documentation just to understand, how a patch system works, that you
normally don't use. But this problem can be easily solved by shipping
the content you proposed for README.source with dpatch or quilt.
*Only* if the build system differs, people should put additional
comments into README.source. I could at least agree to force people to
make a comment like
"[..] This package use (quilt|dpatch). ...
... read /usr/share/doc/(dpatch|quilt)/README.source [..]."
or similar to this file *if* they use additional tools, so other
maintainers don't need to waste time to find out, which systems are
used. But to be honest, even this sentence is IMHO a waste of time,
because maintainers should be able to figure this out within a minute if
there is nothing unusual.
I cannot agree to this proposal. It just increases the package sources
by shipping the same text in several package sources for exactly no
profit. You can make this whole thing much easier by filing 2 (or a few
more) serious reports against dpatch and quilt (and other tools you
consider) to ship these files and then we also don't need a mass-bug
filing after Lenny.
 If you want to work with quilt or dpatch, it must be installed, so
also every documentation shipped with these packages is available.