Use a single version number for protocol releases #148
Description
- Proposed
- Prototype: Not Started
- Implementation: Not Started
- Specification: Not Started
Summary
Use a single version number v<major>.<minor>.<patch> for releases of the protocol repository and remove all individual file versions.
Motivation
The Harp protocol repository aggregates multiple specification assets, including the binary protocol, the synchronization protocol, the core register specification, and the meta-schema for the device interface (device.yml) files. Currently each of these assets is versioned independently in the repository, with versions and changelogs added explicitly inside the content of each asset, e.g. at time of writing the below is the version table:
| asset | version |
|---|---|
| BinaryProtocol-8bit | v1.4.1 |
| BinaryProtocol-32bit | v0.1 |
| Device | v1.12.0 |
| SynchronizationClock | v1.1.1 |
| device.json | draft-03 |
| PhysicalConnector | ?? |
Needless to say, this is extremely confusing both to understand for a newcomer, and to keep consistent as a maintainer. Furthermore, it makes it practically impossible to track compatibility between different file versions within the spec, and of course impossible to assign compatibility of devices with the standard using only one number (one would need multiple such numbers spread out over multiple different sub-components).
Detailed Design
Avoid using separate versions for individual files and instead provide a single version number v<major>.<minor>.<patch> representing a public combined and tightly knit release of the entire repository.
Each public release represents a single snapshot of the combined bundle of assets (binary protocol, synch protocol, device registers, interface meta-schema, etc) required for device and client compliance. ALL specifications must be implemented by devices or clients aiming to comply with a specific version of the protocol.
It is up to the developers and maintainers of each device or client to decide which version of the protocol they want to comply with, and advertise that version so we can provide a clear compatibility matrix mapping device or client versions to supported protocol versions, e.g. based on the device interface schema file.
Drawbacks
Not currently known.
Alternatives
There is currently parallel versioning of multiple files in the Harp standard. To do this while keeping compliance provenance would require having different ways to explicitly track compliance with each of these levels separately. This would increase the complexity of any solution to a point where we believe it to become effectively intractable given current developer resources.