Wandering Thoughts archives


How you should package local-use configuration files

Some packages ship with systems of split configuration files, where there is a standard configuration file (or several) and then a file that is specifically designed to be customized by the local system administrator. The intention is that the sysadmin can make changes to the local-use config file without having to worry about the package's updates to the standard configuration (and thus without having to merge their changes and the package's changes). Unfortunately packages often make a tragic mistake in the contents of these local files.

It's really simple: local-use config files shouldn't have anything that your package will ever change. A local-use config file should have no long helpful comments documenting everything, no sample items, no anything. All it should have is a comment saying roughly 'this is where you make local changes; for a discussion of what can go here, see ...'.

(And the contents of that comment should be designed so that they don't have to change.)

All of the documentation comments and commented out examples and so on are well intentioned but fatally flawed. It's almost guaranteed that at some point the upstream package will decide (or need to) rewrite the documentation, add or fix examples, and so on. At that point you've created a change conflict: both your package update and the local sysadmin have changed the same file and it's up to the local sysadmin to reconcile the result (or to ignore it, which has various consequences). And this is a packaging failure.

Sometimes the upstream package will ship with such a content heavy local-use configuration file. You should not package this file as is; instead you should move it to be a documentation file and package a new minimal file as the local-use configuration file.

(One package that commits this error is the privoxy RPM for Fedora. Its /etc/privoxy/user.action file is just full of helpful comments and examples, which of course have sometimes changed between versions.)

linux/PackagingLocalConfigFiles written at 23:44:45; Add Comment

Page tools: See As Normal.
Login: Password:
Atom Syndication: Recent Pages, Recent Comments.

This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.