Holoseat

h1. Versioning Scheme

{{toc}}

h2. Terms

|hw|Hardware|The physical components of Holoseat which are encumbered with version related compatibility concerns|

|sw|Software|The user application and the REST API|

|fw|Firmware|The code running on the controller itself interacting with the sensors and the game|

h2. Goals

# Ensure only compatible versions of hw/sw/fw are connected to one another so users do not experience issues stemming from compatibility mismatch

# It should be easy to identify a compatible set of hw/sw/fw from version their numbers

# Bring consistency and rigor to versioning process moving forward

h2. Assumptions

# hw rarely changes

# hw changes only occur as part of production runs

# hw includes all electro-mechanical elements of the system (so sensor and tone ring are hw, but bike pedals are generally not since they are interchangeable)

# fw is coupled to hw (hw must support the fw access to sensors, etc) and to sw (sw uses the HSP in the fw to implement REST API and to interact with the hw)

# Looking for a scheme where parallel version numbers across hw/sw/fw indicate compatibility

h2. Defining Levels of Versioning

* Version numbers may be multi-digit, aka, v1.0.9 does not automatically become v1.1.0 on next patch, it becomes v1.0.10

* Product - the top most level of compatibility grouping, defined by the principle capability set.  There is no expectation of hw/sw/fw compatibility between products.  Each product has its own version history.  Examples of products:

** Holoseat (standard) - current development effort, requires a PC for use, emulates HID devices but does not proxy for HID devices.  Not suitable for consoles.  May require additional software (such as key mapper) for users who wish to achieve similar results to proxying HID devices

** Holoseat Advanced - next major development effort, utilizes system on a chip to replace need for PC and to implement HID proxy.  Will enable use of Holoseat with consoles.

* Major - a version of a product with significant feature changes from the previous version of the same product.  There is no expectation of hw/sw/fw compatibility between major versions.  Major versions should be reserved for introduing changes that require hardware upgrades (e.g. changing the type of sensor used or the number of poles in a tone ring) but don’t fundamentally change the nature of the product (e.g. the same capability but implemented in a new manor or adding new way to support the capability, specifically in a way that does not require a new architecture for the system).  

** Adding BLE to the standard Holoseat so it can connect to tablets or phones would be a major version change as it requires a hardware upgrade, but that upgrade just means adding a new outbound HID path which is in line with the existing architecture. 

** Supporting proxy for HID devices would be a product change as it means adding an inbound HID path and all the code and potential hw needed to implement the proxy behavior.

* Minor - a version of a product with incremental feature changes (e.g. additions or marking of existing features as deprecated) not requiring a hardware change.  Used to bring improved experience to existing users.

* Patch - a version which does not add any new behaviors.  Used to introduce bug fixes or refinements.  Patch level should never impact compatibility.

h2. Versioning Matrix

||*Product*|*Major*|*Minor*|*Patch*|

|hw|Determined by USB VID/PID|Identified in hardware by version resistor|Not Used|Identified by physical markings|

|sw|Identified by string constant|\3. Identified by string constant of form Major.Minor.Patch| 

|fw|Identified by string constant|\3. Identified by string constant of form Major.Minor.Patch|