Why my commit messages for configuration files describe my changes

April 10, 2020

Over the years, I have wound up adopting a particular and somewhat unusual style of commit message for many of my changes to system files like /etc/group, to things like DNS and DHCP control files, and to configuration files. The unusual thing I do is that in my commit message I don't just say why the change is being made, I say what the change itself is (in the abstract). For instance, for a change to our /etc/group, I might say "added <x>, <y>, and <z> to group 'fred'" (with the <>'s as part of the text, because '<cks>' is our local style for writing out logins).

On the surface, this is strange. What I changed is right there in the diff itself; putting it in the commit message appears redundant and feels somewhat like putting a '// add x and y together' comment in code. However, this is not quite true. The diff is what I did change, while the commit message is what I intended to change. When all goes well, the two are the same. But things don't always go well, and when that happens having an explicit description of the intent can be important.

Of course, programmers can have this problem too. But as a a sysadmin and sometimes programmer, I've wound up feeling that sysadmins are both more prone to this problem and better placed to be able to deal with it with commit messages. On the bad side, many more mistakes with the files we deal with are perfectly valid and functional results, just not what we intended. And generally we don't have the sort of tests that programmers do, which would catch some of these mistakes. On the good side, many of our changes are small enough that what we intended to do can be described in high detail in a short commit message, in a way that's not the case for many code changes.

(Generally, our intentions will also appear in our worklog system. But having them in the commit message saves finding the relevant worklog, and since I generally commit right after looking at a diff (and with it still on the screen), writing out what the diff should show may help me actively notice an error.)

PS: It doesn't help that many control and configuration files are rather less readable than well formatted code is, and often give you diffs where what actually changed is harder to see than in most code changes. If you're just adding a login or two to a group, a diff of /etc/group has a lot of noise that can make it hard to see the important signal.

Written on 10 April 2020.
« Why you want a Linux bootloader even on UEFI systems
'Deduplicated' ZFS send streams are now deprecated and on the way out »

Page tools: View Source, Add Comment.
Login: Password:
Atom Syndication: Recent Comments.

Last modified: Fri Apr 10 00:50:44 2020
This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.