Semantic Versioning for Electronics Design

Tags:

Updated: 2025-05-20

Summary

This is a practical system for versioning and tagging electronics to streamline prototyping and development. It mirrors Semantic Versioning 2.0 described here but adapts to the realities of hardware. This convention is intended for printed circuit boards (PCBs) and printed circuit board assemblies (PCBAs).

Here we change PATCH to SUBREVISION as PATCH is a software specific term. Given a version number MAJOR.MINOR.SUBREVISION (analog of MAJOR.MINOR.PATCH), increment the:

MAJOR: When you change the interface or mechanical form factor
MINOR: When you change the layout or schematic
SUBREVISION: When you change the BOM or population option

Major Version: Interface & Form Factor

Roll the MAJOR when any of the following occur:

Board size or shape changes to fit a new enclosure
Input/output voltages or signal levels change for system compatibility
New interfaces are added (USB, Ethernet, analog output, etc.)
Features are added or removed entirely
Connector types change for system compatibility

A major revision should define the physical layout clearly. Include board outlines, drawings, and mechanical models.

Tip: Tools like kicad-parts-placer can help verify and enforce mechanical consistency.

Minor Version: Schematic & Layout

Roll the MINOR when any of the following occur:

EDA-level changes (layout or schematic edits)
Trace cuts, bodge wires, adding parts without footprints etc.
Stackup or PCB material changes
Changes in surface finish (ENIG vs. HASL, etc.)
Minor outline changes that don’t break the mechanical fit

In general minor revision will contain their own EDA files. All changes should be documented in a changelog.

It should also have a schematic, either a clean one for that revision or a base schematic plus a list of DNPs and mods.

Subrevision: BOM & Population Variants

Roll the SUBREVISION when any of the following occur:

Changing part values
Changing manufacturer part numbers
Bridging or opening jumpers
Populating or depopulating optional subcircuits

Subrevision versions do not imply a new board design. They are built on a specific MAJOR.MINOR revision and represent different assembly options.

A subrevision may have its own schematic, though this isn’t always practical (e.g., one bridged jumper). Regardless, document all changes in the README and a changelog.

Batch ID or Manufacturing Date

When the same Major.Minor.Subrevision board is made at a different time those should be tracked in case there is a systematic problem. Use a batch ID, assembly date, or lot tracking metadata to distinguish builds.

Final Summary

Level	Trigger Examples	Files to Track / Artifacts
MAJOR	Mechanical fit, I/O changes, connector swaps	3D models, outlines, interface docs
MINOR	Schematic edits, layout changes, finish or stackup	EDA files, schematic, changelog
SUBREVISION	Part swaps, population options, BOM tweaks	BOMs, README notes, changelog, optional schematic diff
Batch ID	Assembly time or fab change (same logical design)	Build metadata, lot tracking

Example Directory Structure

This example is for KiCad projects but is not specific to it.

my_project/
├── README.md                       # Top-level project overview
├── v0.X.X/                         # Major revisions (interface/mechanical changes)
│   └── README.md                   # Overview for major revision v0
├── v0.1.X/                         # Minor revision 0 (initial schematic/layout baseline)
│   ├── README.md                   # Overview for v0.1.X series
│   ├── my_project/                 # KiCad project directory
│   │   ├── my_project.kicad_pro    # KiCad project file
│   │   ├── my_project.kicad_prl    # KiCad project local settings
│   │   ├── my_project.kicad_sch    # Schematic file
│   │   ├── my_project.kicad_pcb    # PCB layout file
│   │   └── sym-lib-table           # Symbol library mapping
│   └── CHANGELOG.md                # Changelog for v0.1.X series
├── v0.1.0/                         # Specific subrevision (BOM or assembly variant)
│   ├── v0.1.0-20250101/            # Manufacturing files & outputs
│   │   ├── gerbers/                # Gerber files
│   │   ├── drill/                  # Drill files
│   │   ├── ipc2581/                # IPC-2581 export
│   │   ├── mechanical              # 3D mechanical models & Outlines
│   │   └── ...                     # Additional release assets
│   ├── bom/                        # BOMs and population variants
│   │   ├── bom_full.csv            # Complete BOM
│   │   └── bom_variant_dnp.csv     # BOM with Do-Not-Populate entries
│   ├── README.md                   # Overview for this exact revision
│   ├── CHANGELOG.md                # Changes since v0.1.X
│   ├── schematic.pdf               # PDF of schematic
│   └── version.txt                 # Explicit version tag (optional)
├── v0.1.1/                         # BOM or population-only change
│   └── ...
├── v0.2.X/                         # New minor revision (updated schematic/layout)
│   └── ...
├── v0.2.0/                         # First BOM/assembly release for v0.2.X
│   └── ...
└── archive/                        # Deprecated files and experiments
    └── ...