[arch-general] Packaging: difference between "example documentation config" and "default config"

[Jakub Klinkovský]

Hi all,

there are two kinds of config files shipped with Arch packages:
 1) "example documentation config" - by this I mean sample config files,
    intended for documentation purposes
 2) "default config" - by this I mean configs containing sensible default values
    uncommented to provide basic functionality ootb
One of the recognition signs is that in Arch, 2) configs are usually very short.

Some examples of proper "default configs":
    /etc/ntp.conf
    /etc/pacman.conf
and of "example documentation configs":
    /etc/dnsmasq.conf
    /etc/wpa_supplicant/wpa_supplicant.conf
    /etc/hostapd/*
    /usr/share/doc/lighttpd/config/*

Now the problem is: should "example documentation configs" be installed in /etc/
or /usr/share/doc/<package>/ ? I'd vote for the latter, here is the reasoning:

1) Users will hardly overwrite files in /usr/share/doc/ so keeping "example
documentation configs" there will ease maintenance of short and much clearer
separate config files.

2) In the examples above, in all dnsmasq, wpa_supplicant and hostapd, the
decision to keep the configs under /etc/ is made in PKGBUILD [1], [2], [3]. In
case of wpa_supplicant, wpa_supplicant.conf(5) even indicates that the path to
example config is "probably" /usr/share/doc/wpa_supplicant/.

3) Keeping "example documentation configs" with uncommented options under /etc/
might lead to unintended behaviour, meaning the default options might not be
very sane. Specifically, /etc/wpa_supplicant/wpa_supplicant.conf has multiple
network blocks uncommented, which, in conjunction with the recently introduced
dhcpcd hook [4], may lead to wpa_supplicant being started without user's
intervention and not failing due to the network blocks uncommented in
wpa_supplicant.conf.

4) Considering the user-centric clause in the Arch Way [5], I don't think any
default config file for the three packages is necessary as anybody using it will
have to modify it. Creating the file instead of modifying some bloated sample
should be easier, see point 1).

Before I submit bug reports for the three packages (dnsmasq, wpa_supplicant,
hostapd), I'd like to hear some more opinions about this. Thanks,

--
jlk

[1]: https://projects.archlinux.org/svntogit/packages.git/tree/trunk/PKGBUILD?h=packages/dnsmasq#n37
[2]: https://projects.archlinux.org/svntogit/packages.git/tree/trunk/PKGBUILD?h=packages/wpa_supplicant#n42
[3]: https://projects.archlinux.org/svntogit/community.git/tree/trunk/PKGBUILD?h=packages/hostapd#n55
[4]: https://wiki.archlinux.org/index.php/Dhcpcd#10-wpa_supplicant
[5]: https://wiki.archlinux.org/index.php/The_Arch_Way#User-centric
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 836 bytes
Desc: not available
URL: <http://mailman.archlinux.org/pipermail/arch-general/attachments/20140528/138763e5/attachment.asc>