Bill of materials that ships with the repo

Keep the list where the design lives

Every hardware project generates a bill of materials. Most of them end up as orphaned spreadsheets on your desktop, accurate for exactly one prototype run. When you return three months later—or when someone else forks your repo—the part numbers drift, the vendors change, and nobody remembers which MOSFET you actually used.

Store the BoM in the same repository as your schematic and board files. Use a format that diffs cleanly: CSV, YAML, or even a markdown table. Version it with Git so you can trace which parts belonged to which board revision. When you spin a new PCB, update the BoM in the same commit that changes the schematic. Treat them as a matched pair.

Structure that survives the next order

A useful BoM captures more than part numbers. Include the manufacturer name, distributor SKU, and a plain-English description that still makes sense when the vendor redesigns their catalog. Note the package size and tolerance so you don't accidentally swap 0603 for 0805 mid-build.

Add a "notes" column for substitutions you've tested. If you've verified that three different LDO regulators work in the same footprint, write it down. Future you—or the person assembling your design—will skip an afternoon of cross-referencing datasheets.

Quantity matters. List the count per board, not the reel size you bought. When someone scales your project to ten units, they shouldn't need a calculator and your Digi-Key order history.

Link from the README

Your README should point directly to the BoM file. One sentence, one hyperlink. Anyone cloning the repo will find it without hunting through subdirectories or guessing filenames.

If you maintain multiple board revisions in the same repository, keep separate BoMs and name them clearly: bom-v1.2.csv, bom-v2.0.csv. The README can list all active versions. Deprecate old ones by moving them into an archive/ folder, not by deleting them—someone will eventually need to repair a v1.0 board.

Automate the boring reconciliation

Most schematic tools export BoMs automatically. Use that feature. Set up a script that runs after every board update and writes a clean CSV to your repo root. If your EDA software generates XML or some proprietary format, write a ten-line Python script to convert it into something human-readable.

When the BoM lives in version control and updates with the design files, it stops being a chore you forget. It becomes part of the build artifact, shipped with every release tag. That's when documentation starts pulling its weight—and when someone else can actually build your circuit without an hour of detective work and three clarifying emails.

Parts change. Vendors disappear. The BoM that lives in the repo is the one that survives.