Version your hardware like you mean it

The problem arrives six months later

You built three boards. They look identical. One works, one doesn't, one works differently. You stare at the Gerbers folder and realize you have no idea which design shipped when.

Hardware versioning isn't git. It's slower, more expensive to fix, and the artifacts live in drawers instead of repos. But the documentation habits transfer cleanly if you treat the silkscreen like a commit message.

Silkscreen the date and hash

Every board gets a version string on the silkscreen: v1.2 2024-12-15 a3f9c0. That's semantic version, build date, short git hash. Seven extra characters of copper that turn a mystery board into a known quantity.

The date matters more than you think. "Was this before or after I fixed the pull-up?" becomes a five-second answer instead of a half-hour archaeology dig. The hash is insurance: if the date's ambiguous, you can pull the exact schematic.

Some folks skip the hash and rely on the date. Fine for solo work. But if you're ever handing a board to someone else—or to future you after a hiatus—the hash is a kindness. It eliminates guessing.

Keep a build log

A hardware-log.md in your repo maps versions to reality. One line per build:

v1.2 | 2024-12-15 | a3f9c0 | 5 boards | JLCPCB | fixed R7, added test pads
v1.1 | 2024-11-03 | 7b21ef | 2 boards | OSH Park | first attempt, no ESD

This log lives next to the KiCad files. It's not fancy. It's a timeline you can grep. When a board misbehaves, you know exactly what you built and what changed since.

The "notes" column is where you write down the things you'll forget: which resistor value you swapped at the last minute, which connector footprint was wrong, which trace you hand-soldered because the via didn't plate. The README is a joint—the build log is the same deal for hardware.

Tag your repo when you order

Before you send Gerbers to the fab, tag the repo: git tag hw-v1.2 -m "Order #5, JLCPCB". The tag freezes the design. If you need to rebuild that exact board a year later, you check out the tag and regenerate.

This also prevents the worst failure mode: ordering a board, then tweaking the schematic while you wait, then receiving the boards and wondering which version you're holding. The tag is proof.

Serial numbers for anything you ship

If the board leaves your bench—gift, sale, collaboration—it gets a serial number on the silkscreen: SN:0023. Just an incrementing integer. Keep a spreadsheet or a ContentMine-style inventory doc that maps serial to version, recipient, and any custom mods.

Serial numbers turn "that board I sent you" into SN:0023, v1.2, shipped 2024-12-20. When someone emails "it's not working," you know exactly what they have.

Make it cheap to be right

Versioning costs almost nothing. A few extra silkscreen characters, a markdown file, a git tag. The payoff is huge: you can rebuild, debug, and iterate without losing the thread.

Hardware moves slower than code. That's exactly why the documentation has to be tighter.