Don't prefill config files

Don't prefill config files

Feb 1st, 2024
by makeworld

The biggest design mistake I made with Amfora, my first community open source project, was autogenerating config files. On startup, the application looks for a config file, and creates one if it doesn’t exist, full of all the application defaults. At the time, I thought this was great, as it documents all the existing options, and makes them very visible to the user in case they want to change them. In the end, this decision created a lot of headaches and is not something I’d ever do again.

It feels obvious now, but this issue wasn’t to me at the time. The problem is you can never change any defaults. Here’s a real issue from Amfora: Alice installs v1 of my code, that uses search engine A. The search engine is of course configurable, and so by default search_engine = A gets put in her config file. A little while later, search engine A goes down forever, and so the wise developer (me) changes the default search engine to fancy new search engine B. But when Alice installs v2 of the application, it reads search_engine = A in her config file and will never use the new default! Alice would have to read the release notes and manually make the change herself, which is a pretty big ask.

This gets worse for interrelated config keys, like for theming. Amfora has multiple config keys to set the colour of various UI elements, and occasionally new ones are added. If all these keys were set in the config file by default, then the default theme could never be changed. For example, imagine a v3 that adds a new theme key like button5_colour, and also changes the default theme. For users with the application preinstalled, they would see the old theme like before from their config file, except the new “button 5” would have a colour from the new theme, looking weird or even invisible. In Amfora’s case this was thankfully avoided as theme keys were not kept in the default config.

The solution

Many applications on my laptop and server appear to solve this problem in a half-baked manner, where all the configuration keys are indeed written to the config file, but as comments. Technically this avoids the problem described above, but I’m not a fan since this can mislead the user. When the application is updated and the defaults change, these comments will then be out of date, possibly leading to some frustating debugging sessions. (“I swear IPv4 was already disabled!”)

In my opinion the solution to this is simple: the user has to write the config options themselves. At most the application could create the file with just a few comments, instructions on how to find documentation (manual, web page). This way the only options in the config file are the ones that the user manually written in. Only those will remain in place when application defaults are changed.

All works on this site created by me are licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. They may not be used for commercial purposes.