Rectify and document our versioning system about parsec

[paulhowardarm]

This captures the issues well.

A couple of things I think we should really try to make clear in the docs:-

• Our design allows the wire protocol format and version to change, but we don't expect this to happen often, and it may not happen at all.
• The wire protocol version number is not the means of finding out the level of support for specific operations in the API. We don't have a model where a client needs to ask the version number in order to find out whether an operation is supported. Version numbers are nothing to do with the API. Clients should call ListOpcodes to find out whether an operation is supported on a per-provider basis.

The "service version" is really only a special case of the provider version. In the docs, it might be a good idea to explain how provider versioning works to begin with, and then indicate that the core provider represents the overall service.

Also, out-of-process co-services are not the only reason why providers need independent versions. This could happen whenever a provider is an independent binary. For instance, it could be a dynamic library.

We will need to make sure it is very clear that provider/service versions and wire protocol versions are totally unrelated. The provider/service versions are implementation versions, whereas the wire protocol version is an interface version.

Lastly, it might be worth a specific statement to say that individual opcode interfaces are not versioned. We use the open/closed principle here. (I think there are words to this effect in the "general principles" section of the API docs, but there can't be harm in repeating them elsewhere). Once an opcode is introduced, its interface is defined and remains the same forever. If we need to modify the interface, we introduce a new opcode with the new signature.

[hug-dev]

Resolved by:

• changes in the book
• changes in Parsec #110