Bug#495233: debian-policy: README.source content should be more detailed
On 15/08/08 at 11:01 -0700, Russ Allbery wrote:
> Giacomo Catenazzi <cate@debian.org> writes:
> > Lucas Nussbaum wrote:
>
> >> First, section 4.14 should list things that one does not need to
> >> describe in debian/README.source. For example, the use of one of the
> >> "standard" patch systems (quilt, dpatch, simple-patchsys) doesn't need
> >> to be documented, since every NMUer should be able to work with them.
>
> I don't agree. This was one of the things that came up specifically in
> the original discussion that led to the README.source compromise. If
> nothing else, README.source tells people that yes, this is bog-standard
> quilt or dpatch, so they don't have to figure out which it is and they
> don't have to wonder whether there's something weird at work.
>
> I would like this file to continue to contain pointers to the standard
> documentation for quilt or dpatch if those patch systems are used. We
> allowed for a pointer specifically so that all you have to do is include a
> line or two of reference. For example, I use:
>
> | 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. Please see:
> |
> | /usr/share/doc/quilt/README.source
> |
> | for more information on how to apply the patches, modify patches, or
> | remove a patch.
>
> quilt and dpatch could probably usefully recommend boilerplate text.
>
> >> Another example is build systems: cdbs is used by >20% of our packages,
> >> so I don't think that one need to document its use.
>
> > I think the better way is do it similar to copyright: for common
> > patch/build system we should include only a link to the relative
> > document. Maybe on a common package (build essential or dpkg-dev) or on
> > patch system package (but in this case we should push stronger the
> > maintainer to include the relevant informations).
>
> Which is what Policy already says, and quilt, for example, provides such a
> document for README.source to link to. So I don't think Policy should be
> changed here.
But that won't work if we want to include more info in README.source.
What about moving to a machine-parseable format, such as:
Patch-system: quilt
Patch-system-doc: /usr/share/doc/quilt/README.source
--
| Lucas Nussbaum
| lucas@lucas-nussbaum.net http://www.lucas-nussbaum.net/ |
| jabber: lucas@nussbaum.fr GPG: 1024D/023B3F4F |
Reply to: