A useful hardware repository answers three different questions:
- What is the design? Schematics, board layout, libraries, and mechanical models.
- Why is it this way? README files, revision notes, constraints, and verification reports.
- What exactly can be manufactured? A named release package tied to a source revision.
Keep source close to its dependencies
If a design relies on a custom symbol or footprint, keep it in the repository and reference it with project-relative library tables. A clone should not silently depend on files that only exist on one engineer’s laptop.
Separate experiments from releases
Koyomi contains multiple compact variants. Some are fully routed fabrication candidates; another is a smaller mechanical floorplan with intentionally unrouted connections. Both are valuable, but they must not look equally ready to order.
Status belongs beside the files:
- tested means physical hardware has been exercised;
- fabrication candidate means outputs and checks are prepared but the exact revision may not have been assembled;
- mechanical study means it exists to validate size and placement, not electrical readiness.
Make generated artifacts auditable
Generated manufacturing files are easier to trust when the repository includes checksums, tool reports, the source commit, and a short release manifest. Large renders and archives can live in object storage, but the repository should retain enough metadata to find and verify them.
See the hardware repository anatomy wiki for a practical directory layout.