minor release 1.3.0 was not backwards compatible

[jackfoxy]

I just upgraded from 1.2.21 to 1.3.5 and apparently ran into the renaming in core API that occurred in 1.3.0. According to semantic versioning this should have been a major (2.0.0) release because of the breaking change

FsPickler.CreateBinary() ==> FsPickler.CreateBinarySerializer()

All well after I changed my code.

[eiriktsarpalis]

Thanks for the feedback. TBH we aren't really using semantic versioning in our releases, something that we might be willing to reconsider given that so many people are using our stuff. For the record, breaking changes are being included in minor releases at the moment.

Speaking of compatibility in general, I've found this to be an elusive problem in the context of distributed applications. In serializer libraries in particular, one definition of backwards compatibility incorporates the ability to deserialize pickles generated by earlier versions. By experience I have come to realise that even minor revisions in the codebase may have unintended consequences in terms of serialization output, without these ever touching code related to the serialization format. This has created problems with users that have adopted FsPickler in production, particularly when using it to persist data (see for example #57).

Things get even worse with libraries like MBrace, which fundamentally submits arbitrary user functions for remote execution. Because of the naming scheme used by the F# compiler for generated closure types, it often means that even adding a single line of whitespace above a certain piece of code will effectively break backwards compatibility. In practice, this means that any two releases of MBrace are mutually incompatible. If you're interested, there's a more in-depth discussion of this here.

[jackfoxy]

I am persisting pickles for production use, but I did this in full knowledge that a serialization incompatibility might come along, so I only do it in cases where I can live with the consequences. I suggest being up front in the documentation about the potential for incompatible backwards serialization and not worry about it too much in engineering future releases.

I encourage you to adopt semantic versioning for API compatibility, however.

[mavnn]

👍 for semantic versioning of API compatibility - we use FsPickler in the full knowledge that serialization may not be compatible between even minor releases (we use it only for transient point to point messages), but the API change would have taken us by surprise.