Bug#495233: debian-policy: README.source content should be more detailed
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.
>> Also, it would be interesting to extend the use of debian/README.source
>> to other areas, such as:
>> - whether the maintainer encourages commits for other people directly to
>> the package's VCS.
>> - the branch layout in the package's VCS.
There was some discussion of this on vcs-pkg, and I'm inclined to agree.
The one potential argument against doing this is that README.source was
intended to document the source package, and those aren't aspects of the
source package, but I think the benefit outweighs a division of topic here
and it's reasonable to put in this file anything that's relevant to
someone wanting to modify it.
--
Russ Allbery (rra@debian.org) <http://www.eyrie.org/~eagle/>
Reply to: