This section describes the protocol used for communication between the WebIssues client and server. This is work in progress, for now only the backward compatibility problem is described.
This NEEDS A LINK TO THE PROTOCOL ?? pedro
The general principle is that a client should work with both a newer version of the server. Otherwise each upgrade of the server would require upgrading all client workstations and that can be pain.
Because of this, the changes to the communication protocol should be backward compatible. It means that the syntax and semantic of existing commands cannot be changed, but new commands can be added. This is very much like binary compatibility of shared libraries.
The client should check the version of the server it's connecting to. If the version of the server is newer than the latest known version, the client will simply not take advantage of the new functions that are available. If the version of the server is older, the client will disable functions that are not supported by the server. The server's version is returned in the X-WebIssues-Server header (available since version 0.8.3).
From time to time there is a need to make changes which are not backward compatible. That's for example the case if we decide that deleting or moving issues between folders should be possible. For that purpose the X-WebIssues-Version header is used (currently it's 0.8).
The client will never work with a server using a newer version of the protocol. It may or may not have a compatibility mode for older versions, depending on the need and effort required to maintain such compatibility. The server doesn't need to know anything about the client and it will always use only one version of the protocol. It's the client's responsibility to check and adjust to the server's version.
To reduce the impact of changing the protocol version, this should be done as rarely as possible. Multiple changes should be merged together and they should be only done in the development version until a production version is released. Also the previous version of both the client and server should remain maintained for some time (bug fixes etc.).