Semantic versioning for electronics design

README.md

The following is a system for versioning and tagging electonics to enable faster prototype and development. Semantic versioning is used with the following sections

1. Major: Interface & form factor
2. Minor: PCB changes
3. Subrevision: BOM changes

Major

Changes that would lead to rolling the major revision are:

• Changing the size to fit a new enclosure
• Changing the input or output voltages to interface with a different system
• Adding additional interfaces (USB, ethernet, analog output, etc)
• Adding or removing large sections of components to other boards
• Hacking different connectors to interface with a different system

A major revision should contain a form factor description using kicad-parts-placer or similar and a model of the board outline. The mechanical design can live in this section.

Minor

• Cutting traces and wiring jumpers during debug or prototyping
• Any EDA changes to a board
• Stackup changes
• Major changes in board finish
• Minor outline changes
• Putting a capacitor over a resistor to change an amplifiers bandwidth

A minor revision either has EDA files associated with it or a list of changes to be made to an existing board. This should be in the README along with a description of the changes. A minor revision will need to have a schematic to be able to make the board layout and that schematic can either be that of subrevison 0 or a generic list of DNPs.

Subrevision

• Changing part values
• Changing manufacture part numbers
• Bridging jumpers
• Populating/Depopulating a section of parts
• Hardware related firmware changes

A subrevision does not have a unique board, it relies on a known interface and board design. It will have it's own schematic (or could have it's own, it may not be wise making a schematic for a single bridged jumper). A subrevision has a PCB as a component in its assembly. Several subrevisions may differ only by the PCB they are on but are still different part numbers. If this is the case this must be noted in the README.md. These should be stored seperately and tracked. They have become different products so may need to diverge but the relationship shouldn't be forgotten.

A subrevision should reference the PCB it is intended for but never include on it it's repository.

There are several special cases that require an additional set of data.

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.

Firmware Changes

Software has it's own versioning system that is not discussed here but some of the software is tied to the hardware. The firmware may need to track changes in the hardware or vice versa. In the case where software has an effect on the performance of the hardware this needs to be tied to the subrevision. It may be wise to minimize this interaction, instead encapsulating the firmware/software version requirements in the assembly number.

Assembly Numbering

The hardware has a part number as does the final assembly. The hardware number is the target use of the electronics assembly as is the assembly number. It can be turtles all the way down with an endless number of assembly numbers (just read your average requirements.txt in a python library). The assembly number is has similar requirements but is not identical to hardware numbering mostly due to the oddities of EDA design.

Summary

• Major: Mechanical & interfaces

• Minor: PCB changes

• Subversion: Everything else

• Store mechanical design at major level

• Store layout related stuff at minor level

• Store BOM related stuff at subrevision level