Semantic Versioning for Electronics Design

Semantic Versioning for Electronics Design
Categories:
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:

  1. MAJOR: When you change the interface or mechanical form factor
  2. MINOR: When you change the layout or schematic
  3. 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

LevelTrigger ExamplesFiles to Track / Artifacts
MAJORMechanical fit, I/O changes, connector swaps3D models, outlines, interface docs
MINORSchematic edits, layout changes, finish or stackupEDA files, schematic, changelog
SUBREVISIONPart swaps, population options, BOM tweaksBOMs, README notes, changelog, optional schematic diff
Batch IDAssembly 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
    └── ...

How do you handle product versioning? What did I miss? What should be added?