The 'NOT BUILDING' Commit: Honest Version Control
I have a commit message that just says 'Attempting to get daemon running - NOT BUILDING'. It is one of the most useful commits I've ever made.
Not because it is good work. It isn't. The code didn't build. The daemon wasn't running. Whatever I was attempting, I wasn't achieving it. But there's something in the commit message, the capitals, the bluntness, no spin, that I've started to think of as a small act of engineering honesty in a sea of commits that are trying to look competent.
Most commit messages are written for an imagined audience that only reads the message and never looks at the diff or tries to compile the project. We write them like press releases. Refactored connection handling. Updated configuration logic. Improved error handling in daemon mode. These are all accurate and almost entirely dishonest about what was actually happening, which was: I had no idea what I was doing and I was trying things and they were not working.
The 'NOT BUILDING' commits don't do that.
The full sequence is interesting. There's 'Started to add daemon mode stuff into event processor - NOT BUILDING', and then 'Attempting to get daemon running - NOT BUILDING', and then at some point presumably a commit where things started working, though by that stage the message probably moved back into vagueness. The NOT BUILDING phase is documented with unusual clarity. The transition out of it is probably something like 'Daemon mode improvements.'
What I like about the NOT BUILDING commits is that they are honest. This is where I am. This is what I have. Do not trust this. There is something almost generous about it — past me leaving a warning sign for future me, or for anyone else unlucky enough to be working in this branch. Here be dragons. The daemon does not run. Proceed with appropriate expectations.
Compare that to the alternative, which is committing broken code with a message that implies you meant to do this. Refactored daemon initialisation. Wip. Changes. All of these could mean 'this doesn't build and I don't know why yet', but they don't say so. You'd have to run it to find out.
There's a version of commit message advice that tells you every commit should be atomic, intentional, and leave the codebase in a working state. I've read that advice many times. I believe it, in theory. On main, absolutely. In a PR, probably. On a feature branch at eleven at night when I'm three layers deep into something that isn't working. I think the more important thing is to say something true.
The NOT BUILDING commits do something specific: they let me step away. I can close the laptop, come back the next morning, and immediately know what I'm dealing with. I don't have to run the thing to find out if the thing works. I know it doesn't. It says so right there. That's not a failure of process, that's the process working.
There's also something in the act of writing it. Typing 'NOT BUILDING' in capitals requires you to admit, to yourself, that it's not building. Which sounds obvious but isn't always. There's a temptation to write a message that's slightly more optimistic than the reality working on daemon startup that lets you pretend you're closer than you are. The capitals are a commitment. They close off the escape route.
I don't think this scales to every commit. The argument for clean history on shared branches is real, nobody wants a repo where every third message is someone's emotional state in capitals. But I've started to think the advice about always being clean and professional is quietly filtering out information that would actually be useful.
The bug archaeology post I wrote (the Arc thing) is basically an argument that commit messages are dishonest about the hard parts. The NOT BUILDING commits are the exception. They're the ones that say: this is the hard part. I am in it. I have not gotten out yet.
That's not a confession of failure. It's just an accurate description of what software development actually looks like most of the time. The feature branch is a mess. The daemon is not running. There are stash commits with names that don't bear repeating. And somewhere in there, if you're lucky, is the commit where it finally works and you can look back at the NOT BUILDING ones and see exactly how far you came.
Which is, I think, what version control is supposed to be for.