Ensuring backwards compatibility for API changes

[t0mpr1c3]

The desktop software currently rejects communication with the shield if it receives notification that the wrong API version is being used:

ayab-desktop/src/main/python/ayab/engine/state.py

Lines 83 to 89 in 8208efc

	if rcvParam == control.API_VERSION:
	control.state = KnitState.WAIT_FOR_INIT
	return KnitOutput.WAIT_FOR_INIT
	else:
	control.logger.error("Wrong API version: " + str(rcvParam) +
	", expected: " + str(control.API_VERSION))
	return KnitOutput.ERROR_WRONG_API

Ideally the API version should be a parameter for AyabCommunication.parse_update() so that the desktop software can work with whatever firmware is present on the shield.

API versions should be documented explicitly.

[dl1com]

Ideally the API version should be a parameter for AyabCommunication.parse_update() so that the desktop software can work with whatever firmware is present on the shield.

Do I understand correctly that you want to achieve (full) backward compatibility for old firmware versions?

I fear this is a target which makes life very hard...not only that we would potentially have to alter the GUI behavior because of impairments of old firmwares, it also introduces another degree of freedom when trying to track down user issues, as we end up with an amount of possible GUI<->Firmware combinations.

So for me it might be even an arguable way to tie the firmware version directly to the GUI version (which is about the diametral opposite of your proposal ;)).
Reason: When somebody tells she/he is using version 1.2.3, we know exactly which firmware is being used when trying to support.
Plus, we currently do not have a way to ship firmware releases separately. They always have been part of the application. So when updating the firmware and release it to the user, we (currently) need to provide a new application installer anyways. (Though this could be solved by providing a way to download a firmware image separately and put it into a certain folder where the application will find it. We have to evaluate if this would be a practicable way for the users. But: Then you end up with situations like: "You have to download GUI v1.0.0, but take care that you have to download separate firmware image v1.0.1 and put it in the folder!")

tl;dr: Currently, I think have a single version number to talk about makes life easier for both users and devs, though it creates a bit of overhead when releasing a hotfix by being forced to release a new GUI installer...what do you think?

[t0mpr1c3]

Perhaps I should explain myself a bit more, it is possible that I have misrepresented what I mean, or misunderstood what you mean.

The model you describe seems appropriate for version 0.x releases where the API is unstable.

If semantic versioning signals anything, it signals a stable API. I interpret that as meaning that a 1.x firmware should work with a 1.x desktop. That, in turn, means that changes in a 1.x version should be backwards compatible with previous 1.x releases. This is a limited concept of backwards compatibility. All it means is that if we do make breaking changes would have to move to version 2.0 (which is fine!) We can release versions 3.0, 4.0, 5.0, and so on without limit.

Backwards compatibility will actually make things easier going forward because we can, for example, issue bug fixes patches for the desktop software without having to issue a new firmware release each time.

I should say that I do not think a stable API is difficult to achieve, but it will look different than it is now. The API must be more flexible. For example, there should be fewer hard-coded constants in the firmware because the desktop will be telling the firmware which parameters to use at the beginning of each job. We are already moving in this direction by having the desktop signal whether it is using test mode, and what knitting machine hardware is in use, instead of having these things hard coded. We just need to take that direction further.

[t0mpr1c3]

You do make a good point about how the firmware is distributed, but I guess I see a different solution to that.

I think it would be great if we could distribute firmware independent of the GUI installer. Probably the desktop software should look up the latest version on github (or wherever it is built) and download it from there.

Semantic versioning should make this straightforward. If you are using 1.x software, you need to download the latest 1.x firmware. If 2.x firmware exists, you should be prompted to upgrade the desktop software.

[dl1com]

That, in turn, means that changes in a 1.x version should be backwards compatible with previous 1.x releases.

Ok, that's all I wanted to hear ;) I made the wrong assumption that you might want to support multiple major firmware versions (e.g. 1.x.x and 2.x.x) in a single GUI version - but in fact, our understanding of semantic versioning is the same ;) Sorry for that!

I think it would be great if we could distribute firmware independent of the GUI installer. Probably the desktop software should look up the latest version on github (or wherever it is built) and download it from there.

That would be great!

[X-sam]

Seems like #414 captures the idea for future exploration, can we close this issue?