On Mon, Aug 24, 2009 at 10:33:14PM +0100, Chris Lamb wrote:
> Package: debian-policy
> Version: 3.8.3.0
>
> Hi Policy hackers.
>
> I feel there is a problem with ยง4.14 ("Source package handling:
> debian/README.source") that is a little harmful at present.
>
> Basically, I feel that assuming that all packages that use a patch system
> require a README.source is damaging the concept of README.source - as the
> archive grows more boilerplate descriptions on how to invoke quilt et al, I
> fear maintainers will simply not bother to consult this file when examining
> a package.I've been walking over README.source files a while ago, and given the proliferation of just copies of /usr/share/doc/quilt/README.source (et al), I understand your concerns and share them. I was actually planning to come up with some proposal or other once I'd finished looking at the README.source files, but whatever :-) > This is particularly unfortunate as, not only can the file be extremely > useful, I fear it will fuel a cycle of maintainers not updating the file > with information as it does not get read anymore. > > Besides, the concept of boilerplate is hardly anthemic in Debian. > > If the motivation behind README.source is to highlight non-trivial > packaging, then many packages can be presented that are trivial dispite > using a patch system. My own conclusion is that the adoption of dpatch or > quilt is so common that the skills for it may be assumed. > > To get things rolling, I propose that we temper: > > | This explanation should include specific commands and mention any > | additional required Debian packages. It should not assume familiarity > | with any specific Debian packaging system or patch management tools. > > ... with something subjective like "any non-standard Debian packaging > system". This would still ask maintainers to document the parts of their > packages that would be unfamiliar to most developers, whilst avoiding > maintainers including essays on how to invoke pbuilder and other nonsense. > > Whilst using a subjective like this isn't desirable, it does avoid having to > enumerate specific programs that are exempt from explanation, which doesn't > really smell right for the Policy. Precicely because you're doing subjective things here, I'm not convinced that using this wording is a good plan. > Thoughts? I would instead suggest changing the next paragraph to something like the following: ``In case a package uses a build system for which documentation sufficient to satisfy this requirement exists in a file installed by one of the package's build dependencies, this file should be referred to from the README.source file, rather than copied into it.'' currently, this paragraph says: This explanation may refer to a documentation file installed by one of the package's build dependencies provided that the referenced documentation clearly explains these tasks and is not a general reference manual. Such phrasing will result in README.source files saying "This package uses quilt, as documented in /usr/share/doc/quilt/README.source" which can be safely ignored if the person doing the NMU is already familiar with quilt. However, if the package's README.source says "This package uses quilt, mostly as documented in /usr/share/doc/quilt/README.source except that we do foo in place of bar" Then this will easily trigger alarm bells to anyone doing an NMU that something out of the ordinary is happening here, and that they need to look out for that. -- The biometric identification system at the gates of the CIA headquarters works because there's a guard with a large gun making sure no one is trying to fool the system. http://www.schneier.com/blog/archives/2009/01/biometrics.html
signature.asc
Description: Digital signature
