Bug#250202: Get this over with

[Wouter Verhelst <wouter@grep.be>]

On Mon, Oct 11, 2004 at 02:12:18PM +0200, Florian Weimer wrote:
> * Wouter Verhelst:
> >  	  the file to the list in <file>debian/files</file>.</p>
> 
> > +          When running <prgn>dpkg-source -x</prgn> does not
> > +          immediately give one a directory with editable source, a
> > +          package should provide a file debian/README.source which
> > +          enumerates and documents the debian/rules targets for at
> > +          least <em>unpacking the source</em> and <em>applying
> > +          debian-specific patches</em> (if any, or a simple statement
> > +          that such a target does not exist or is not required if
> > +          none).</p>
> 
> This patch is missing a few <file> tags (see the line I quoted above).

Indeed.

> Furthermore, I strongly urge you to include a requirement to describe
> how further patches can be applied so that they actually end up in the
> resulting package.  You really want to make sure that users can
> successfully apply patches whose changes are not readily testable
> (also called "security patches").

No objection, even if I find that reasonably easy and self-explanatory.

> Pointers to reasonably verbose instructions should be sufficient (note
> that the dpatch manpage doesn't belong into this category, IMHO).

Of course. The point is to make the life of our users easier, not to
make the life of our maintainers harder.

> > +          Although this file is only required in one specific case
> > +	  (see above), maintainers are encouraged to include a README.source
> > +	  file if the layout of the package is not trivial, so as to aid
> > +	  understanding of it, even if the above condition is not
> > +	  fulfilled.</p>
> 
> I'm not sure if this part is required.  Usually, I'm more interested
> in the build process than the actual directory structure.

This paragraph is about more than just the actual directory structure.
The intention is for people to document any special-case things in their
package management; whether those are special-purpose scripts, obscure
debian/rules targets or strange directory layouts is besides the point.

If that wasn't clear, perhaps it should be reworded, but that's about
it.

-- 
         EARTH
     smog  |   bricks
 AIR  --  mud  -- FIRE
soda water |   tequila
         WATER
 -- with thanks to fortune