define rcp version and clarify versioning

[i-n-g-o]

rcp vesion. e.g.: protocol-break.structure-break.minor-and-addoptions

This is the case because adding options only increases the minor version. Major versions changes indicate a breaking change in the protocol (e.g.: changing an options datatype).

Clint down-to versions can only can be major versions which are smaller or equal to the clients rcp-version. This is because minor updates mean they are compatible within the major version.

[i-n-g-o]

Max rcp vers in lib	server comp version	client version	client downto version	result
1.0	1.0	1.0	1.0	ok
2.0	2.0	1.0	1.0	not ok
2.0	2.0	2.0	2.0	ok
1.0	1.0	2.0	1.0	ok
1.0	1.0	2.0	1.0	ok
2.0	1.5	2.0	1.0	ok
2.0	1.5	2.0	2.0	not ok
2.5	2.0	1.0	1.0	not ok
2.5	2.0	2.0	1.0	ok
1.0	1.0	2.0	2.0	not ok
2.2	2.0	2.0	2.0	ok
2.0	1.0	1.5	1.0	ok

[i-n-g-o]

Versioning

Minor changes:

all optional additions:

• add an option to: Datatype, Widget, InfoData, Parameter
• a new optional packet type
• a new datatype, widget

Major changes:

all non-optionals add/modify/remove

• non-optional in Datatype, Widget, InfoData, Parameter, Update packet
• all structural changes: e.g. packetstructure, lang string structure
• non-optional packet types
• all removals

Modify optionals:

Two types of modifications:

1. Modifications of optionals which lead to a parsing error
   Could be only minor change
2. Modifications of optionals which do not lead to a parsing error but lead to interpretation errors. e.g.: Change Color RGB to BGR
   Might always be a major change

Discussion remove optionals:

1. Don't allow removals
   Pro: ease of mind - don't worry about it
   Con: cluttering

2. Allow removals only for major changes
   Pro: ease of mind, cleaner protocol major versions, downward compatibility is preserved
   Con: a major change might be too drastic (for things never used)

3. Allow removals also for minor changes
   Pro: Very clean protocol with each minor update
   Con: introduces a contradiction: The server must not send a removal but because it is not using it, its compatibility version would fall down one minor version under the removal-version. The client defines a compatibility-window between its rcp-version and the lowest major down-to version in which we can test for the compatibility of optional additions but not removals. The contradiction is: A removal will lead to the removal of a code-path at the client (minor version increases) but the down-to version would still be a version in which the removed item can be processed. In other words the clients version window defines that something needs to be processable but also defines that the codepath was removed. -> removal means a major version change

4. Allow removals without version change
   Pro: not wasting version numbers
   Con: client would not know what was removed

[i-n-g-o]

Versioning

RCP is using a version consisting of a major and minor version number. The following versions are used in Info Data:

server rcp-version:

The rcp version implemented by the server

server runtime-version:

The rcp version used by the server derived from features actually used

client rcp-version:

The rcp version implemented by the client

client base-version: (backward compatibility version)

The minimum major version the client implements

Compatibility between the server and a client is ensured if the server runtime-version is between the clients rcp-version and base-version (inclusive). See Protocol Flow for the version handshake and more details.

e.g.:

server rcp | server runtime | client rcp | client base | result
-- | -- | -- | -- | --
1.0 | 1.0 | 1.0 | 1.0 | ok
2.0 | 2.0 | 1.0 | 1.0 | not ok
2.0 | 2.0 | 2.0 | 2.0 | ok

Version Changes

RCP aims to encourage the introduction of new features over time without the danger of immediate incomaptilies.

RCP aims to gradually introduce new features without causing problems.

• optional as basis for the protocol
• the version window maximizes the prospect of compatibility between server and client

without causing at making it easy to introduce new protocol versions.

The protocol is designed in a way that compaitibility between server and clients is

The protocol version can change following these rules:
RCP versioning allows to add options
Version changes

New versions:

Consider the following:

Minor changes:

all optional additions:

• add an option to: Datatype, Widget, InfoData, Parameter
• a new optional packet type
• a new datatype, widget

Major changes:

all non-optionals add/modify/remove

• non-optional in Datatype, Widget, InfoData, Parameter, Update packet
• all structural changes: e.g. packetstructure, lang string structure
• non-optional packet types
• all removals

Protocol Flow

Version Handshake:

1. client sends a Info Packet
2. server receives info-packet
3. server sends info-packet to client (consider: or error)
4. server checks if its runtime-version is between client rcp-version and base-version (inclusive)
   4. version ok -> wait for init
   5. version mismatch:
   6. server is strict -> close connection
   7. server not strict -> wait for init
5. client receives info:
   9. version ok:
   10. client sends initialize
   9. version missmatch:
   10. decide to close connection
   11. or client sends initialize and skip packages if a parsing error occurs due to unknown options

Initialization

12. server receives initialize
13. ...