2011-06-27

Textual configuration has comments, GUIs dont.

I have been running the test and merge process for DrizzleDB using Jenkins.

Jenkins is a pretty standard Java-based web app. The configuration settings are stored in XML files, and that configuration is manipulated using an "easy to use" Web GUI.

The "old skool" UNIX-like way to keep configuration settings is in a text file, which is edited with an ordinary text editor, and is read by the program daemon on start or SIGHUP. This is considered "scary", "hard to learn", and "hard to use" by novices.

There is a big problem with GUI-only managed configuration, an issue where text file configuration has a major advantage.

I did not set up the Jenkins server or nodes. I am not the only person with admin access to it. Several other people have set it up, set up various projects in it, and added new nodes and new types of nodes.

As I work on it and look at the existing configuration, I often find things that are "surprising", things that make me say "Is that right? That can't be right? Can it?". And then I have to spend time digging into it. Sometimes it IS right, for reasons I didn't know at that moment. Sometimes it used to be right, but isn't necessary any more. And sometimes, it just wasn't right.

In a textual configuration file, you can put comments. The purpose of a comment is to communicate into the future, to tell those who came after you (including your future self) what you were intending to do, and why you selected some "surprising" option or way of doing things.

There is no good way to put comments into GUI or WebGUI configuration, even if it has a freeform field labelled "comments".


Update, this post is being discussed at Reddit.

Update, this post is being discussed at Forrst Podcast ep 122.
Labels:

6 comments:

  1. HartmutJune 28, 2011 at 2:42 AM

    bonus points for having your text based config files checked into your SCM of choice (even good old RCS may be good enough for this) and being able to review its histrory and to roll back to a previous version if something goues wrong ...

    ReplyDelete
  2. UnknownJune 30, 2011 at 8:22 AM

    I check my Jenkins configuration files into SCM, I do it during a nightly job that runs...inside Jenkins! Adding the ability to comment on configuration items would be an interesting addition to a webgui. I think it would be doable, just add another "expandable" section similar to the help sections in Jenkins, or even add a comment section to that help section.

    ReplyDelete
  3. raphinouJune 30, 2011 at 11:28 AM

    you also have multi-level undo in a text editor. Sounds basic, but so useful!

    ReplyDelete
  4. Lou FrancoJune 30, 2011 at 11:56 AM

    ... and copy/paste, find/replace, etc

    ReplyDelete
  5. UnknownJuly 1, 2011 at 5:58 AM

    We at OpenLieroX actually tried to solve this for game settings. OLX is a 2D shooter-like game.

    In the game settings dialog, for each setting which was changed by the user, it shows a 'reset' button next to it. Also there is a way to just show the changed settings.

    You can also filter the settings by how advanced you want to go (a bit similar like in VLC but with more levels).

    And when you hover one setting, there is a comment section below the dialog which describes the setting.

    ReplyDelete
  6. Marnix KokJuly 13, 2011 at 3:08 AM

    Hi!

    I thought this was a very interesting post, you inspired me to write about the relation between this problem and problems in software architectures.

    You can find it here: http://fourdsoftware.com/blog/evolution-in-configuration-files.shtml

    Cheers,

    Marnix Kok

    ReplyDelete

Subscribe to: Post Comments (Atom)