Use a single version number in device repositories #145
Description
- Proposed
- Prototype: Not Started
- Implementation: Not Started
- Specification: Not Started
Summary
Use a single version number v<major>.<minor>.<patch> for each device repository, e.g. v1.2.0. If specific artifacts are left unchanged, rebuild and/or repackage them for the release.
Motivation
Harp device repositories aggregate multiple development assets, including mechanical and hardware design, firmware, software interfaces, and possibly GUI applications. Currently these are versioned independently in the repository, with separate prefixed tags for different "releases" of each component, e.g. pcb2.0, fw3.1-harp1.11, api0.1.0, app1.0.1.
This is extremely confusing to read and understand when there is only a single development branch (main). The single development branch means that even if tags are prefixed, the diff between two pcb tags can include differences in the software interface or GUI app which are completely unrelated. Furthermore, it makes it practically impossible to track compatibility between different component versions without manually digging into the specifics of each asset.
Detailed Design
Avoid using separate prefixed release tags and provide a single version number v<major>.<minor>.<patch> representing a public combined and working release of the entire repository.
Each public release should contain the bundle of assets (pcb, firmware, interface, app, etc) required for people to actually use a specific version of the device. In documentation, this would also be the version number we would keep track of when talking about installation requirements, operation instructions, etc.
There may well be different hardware targets supporting the device implementation, and these may give rise to multiple distributions of firmware bundled with each release to ensure support for each target, but the different targets should be considered separately from the device "version". We can provide a clear compatibility matrix mapping release versions to supported hardware targets.
Additionally, this would provide a clear aim for CI/CD pipelines: to be able to assemble, for each release, all the interface, firmware, metadata, and other release artifacts automatically and ensure their compatibility. If between two versions a specific component has remained entirely unchanged, it would still be repackaged and bundled with the new release.
Drawbacks
There is currently a need for different teams to work entirely independently in different aspects of a device, and there is indeed potentially a need to mark when each team completed a specific iteration of a design component. However, these could still be kept, see below for a hybrid alternative.
Alternatives
A compromise solution would be to have the v<major>.<minor>.<patch> tags published as official "releases", representing a working aggregation of the latest components, and keep the prefixed tags for internal development metadata purposes only.