Re: Improving documentation on conffiles in Debian Policy and Debian New Maintainers' Guide
Hi Dieter,
Thanks for the suggestions.
> In section E.1 of Debian Policy[0], conffiles[1] are mentioned as a list
> of configuration files that are checked for changes by 'dpkg' during an
> upgrade.
> However, not only files in the conffiles file are checked, but
> automatically also every file in the /etc directory, as mentioned in the
> Debian New Maintainers' Guide [1].
Your assertion that all files in /etc are checked is not correct. dpkg only
checks the configuration files that the binary package has listed as
conffiles.
However, by default, the debhelper build system (via dh_installdeb)
automatically lists all files that are going to be installed into /etc as
conffiles -- that might make it look like all files in /etc are checked but
the logic and control of the situation are reversed. The "by default" is
important here; files in /etc are added as conffiles only if the maintainer
does not take other action. Many packages include files in /etc that are not
conffiles but are handled in some other fashion such as using ucf.
A couple of other comments:
> 1) To make the documentation more clear, the first paragraph in E.1 of
> Debian Policy[0] could be changed with either a reference to the conffiles
> section the Debian New Maintainers' Guide [1]
Policy doesn't tend to refer to other non-normative documents, that is, it
refers to other standards such as the FHS but not normally to other tutorial
documentation. Policy should be the set of rules around which other
tutorials and packages are constructed. Improving Policy so that it is self-
contained is best.
> or by mentioning that files
> in the /etc directory are automatically considered config files, fe. by
> rephrasing the first paragraph :
(Ignoring the earlier confusion about files in /etc being automatically
considered as conffiles by dpkg.)
Since it is only debhelper that automatically includes all files in /etc as
conffiles and use of debhelper is not mandatory (but it certainly is
encouraged!), documenting that particular behaviour of debhelper is not
appropriate in Policy. Indeed, I don't believe there is a single mention of
debhelper or its behaviour outside the footnotes. It is debhelper's job to
help maintainers make good, policy-compliant packages and not Policy's job
to document debhelper's behaviour (dh_installdeb(1) is the appropriate
documentation for this tool).
> 'Any files under the /etc directory are automatically flagged as
> configuration files, or a package may contain a control information file
> called conffiles. This file should be a list of filenames of configuration
> files needing automatic handling.'
As a general point, be careful about whether you're talking about source
packages or binary packages. For source packages, dh_installdeb tool allows
you to have debian/conffiles inside your source package to control what is a
conffile, while otherwise everything in /etc will become a conffile in the
binary package. For binary packages, only the files listed in
control.tar.xz:conffiles are conffiles.
(I suspect, this is actually the root of your confusion.)
> 2) It also makes sense to move the two sentences in section E.1[0] on how
> the conffiles are formatted to the Debian New Maintainers' Guide [1], ie.
> :
>
> 'This file should be a list of filenames of configuration files needing
> automatic handling, separated by newlines. The filenames should be
> absolute pathnames, and the files referred to should actually exist in the
> package.'
It might make sense to document this in the new maintainer's guide -- it
would certainly make sense to document this in dh_installdeb(1) where the
format of this file is not specified at all. Perhaps you could file a bug
against debhelper for that, suggesting a cross-reference to the deb-
conffiles(5) page? (It would also be good if the new maintainer's guide
could point at the documentation rather than duplicate it so that people
learn where these things are actually documented -- perhaps you could assist
with that too?)
cheers
Stuart
--
Stuart Prescott http://www.nanonanonano.net/ stuart@nanonanonano.net
Debian Developer http://www.debian.org/ stuart@debian.org
GPG fingerprint 90E2 D2C1 AD14 6A1B 7EBB 891D BBC1 7EBB 1396 F2F7
Reply to: