Bug#543417: README.source patch system documentation requirements considered harmful
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.
>
> 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.
>
> Thoughts?
1) We should move to new source package format (3.0 etc) that remove the
need for patch system altogether.
2) Documentation for debian/README.source for dpatch and quilt is useful,
and it can be simply supplied in /usr/share/doc/{dpatch,quilt}. Then
debian/README.source only need to say that we use dpatch as documented
in /usr/share/doc/dpatch/README.source.gz.
3) If a package is lacking debian/README.source, then one should expect
that the source is ready to be used. If it not the case, even an empty
debian/README.source is better than none.
Cheers,
--
Bill. <ballombe@debian.org>
Imagine a large red swirl here.
Reply to: