Commit messages for hardware that won't lie in six months

The diff you forgot to explain

You changed R12 from 10 kΩ to 4.7 kΩ, pushed the updated schematic, and moved on. Six months later, you're staring at that resistor in your second prototype, wondering if it's a typo or a hard-won lesson. The commit says "update pull-up." You have no idea which sensor glitch forced your hand.

Hardware version control works when you treat commit messages like field notes. The schematic file shows what changed; the message explains why it had to.

Write for the person who inherits the build

Start with the symptom, not the fix. "ADC noise above 200 mV during motor PWM" beats "changed capacitor." If you swapped a tantalum for ceramic, say why the ESR mattered. If you moved a trace, name the coupling problem it solved.

One sentence for the problem, one for the solution, one for what you tested. You don't need a paragraph—just enough that the next person (probably you) won't have to re-learn it with a scope.

When you're documenting power-supply tweaks or sensor-interface changes, this is the same craft that makes a bill of materials useful instead of decorative. Both are about leaving breadcrumbs that actually lead somewhere.

Tag the hardware revision in the same commit

Your schematic should carry a revision number—silk-screened on the board if you're printing, noted in the title block if you're not. When that number increments, the commit message is where you justify it.

"Rev 1.2: replaced 7805 with LM2596 to reduce heat during 12V input" is a message you'll thank yourself for. "Fixed regulator" is a message you'll curse.

If you're working in KiCad, Altium, or even Eagle, the project files are text-comparable. Git can show you which nets changed, which footprints moved. The message is where you turn that mechanical diff into a decision log.

When the fix touches firmware too

Hardware and firmware changes often travel together. If you adjusted a pull-up because the GPIO couldn't reliably read high, commit both the schematic and the code change in the same atomic commit, and write a message that ties them.

"Increase R9 to 4.7k and add 10ms debounce in main.c—switch bounce was triggering double-counts on encoder."

Now the person reading the code history knows the hardware assumption. The person reading the schematic knows the firmware dependency. Neither has to guess.

This is the same kind of honesty that makes test points worth adding: you're planning for the debug session that will definitely happen.

The README is still a joint

Commit messages are line-level memory. The README is the map. When a hardware revision teaches you something worth preserving, fold it into the README's "Design Decisions" or "Known Issues" section.

If three different commits all mention capacitor placement near the ADC, that's a pattern. Summarize it once in the README, with a link to the relevant commit if someone wants the full archaeology.

For projects that blur hardware documentation and help-text craft, this overlap is where something like ContentMine becomes a peer reference—not because you're explaining networks, but because clear procedural memory applies whether you're wiring a sensor or writing a software onboarding doc.

Commit like you'll clone this in a year

You will. You'll fork your own project, strip out the parts you don't need, and try to remember why the power section looks the way it does. If your commit history reads like a decision log instead of a changelog, you'll rebuild faster and break less.

Write the message that explains the resistor. Future you is counting on it.