Some documentation

[pbiggar]

I recently went through the exercise of trying to understand what changes I could make to my F# types without breaking the serialization, making the notes below. Could these be helpfully turned into documentation of some sort for this library?

All types should be annotated with [<MessagePack.MessagePackObject>], and each field in the record should be annotated with [<MessagePack.Key 0>] (the zero should be replaced with a unique sequential index):

[<MessagePack.MessagePackObject>] type X = { [<MessagePack.Key 0>] x : int

If you forget to annotate all parts of a type (or a type referred to by that type) the serializer will raise an exception. (It seems to be OK to not annotate some variants but not others, so we annotate them all if they are used) Note this is only because we don't use the Dynamic Resolvers.

The following changes to types have been tested. "Safe" changes allow data saved in files in the old format to continue to be read by the serializers for the new format.

The follow changes appear o be safe:

• removing a variant at the end of an Enum (so long as that variant is not used in saved data)
• renaming a variant in an Enum (even if that variant is used)
• rename a field in a record (does not have the be the last field, don't change the keys of other fields)
• remove a field from a record (keep the other fields in the right place)

The following changes appear to be unsafe:

• adding a new variant to an Enum that is not at the end
• removing a variant in an Enum that is not at the end
• reorder variants in an Enum

The following changes have not been tested but are assumed to be unsafe:

• adding a field to variant (eg add b to X(a,b))
• add a field to a record
• change the type of a field in a variant
• change the type of a field in a record
• removing a field from a variant (eg remove b to X(a,b))