Here is an account of our real use case:
We use JSON data format very heavily in our production setup. It is used both in API communication, meta-data saving/loading of some recursive Haskell structures and even in some logs to make it easy to load into splunk and/or logstash. We make use of deriveJSON for the majority of the complex cases instead of hand-rolling error prone instances.
Version 0.6.2, despite being a minor version bump, introduced major, completely backwards-incompatible changes in its TH module. After upgrading to latest aeson and upon inspection of hundreds of runtime errors we got in our dev environment, we noticed the introduction of the new sum type encoding mechanism. We saw that it comes with a new default encoding, which while appearing to be nicer than the old one, uses a completely different encoding structure. There was no mention in haddocks of the changes introduced and how to maintain backwards compatibility.
At that point, ObjectWithSingleField option seemed to offer a way to remain backwards compatible. After fixing some 50+ instances, we saw that even that option did not fit the bill exactly, as it does away with the old wasteful "constructor without fields as a JSON object with empty array" convention. Again, while being a definite improvement, it fails to read serialized objects created by prior versions of aeson.
What is the correct way to maintain backwards parsing compatibility when migrating from 0.6.1 to 0.6.2? Can we possibly create an encoding option that instructs aeson to read and write in its old structure?
In summary, any user of aeson that utilizes the deriveJSON mechanism to persist Haskell structures will run into this migration issue.
Any answers are much appreciated.
Sorry we screwed up a bit with the 0.6.2 release.
Use the following encoding options to have 0.6.1 compatibility.
@bos, now that Hackage 2 is released we could use the preferred package versions feature to maybe deprecate the 0.6.2 release in favor for either 0.6.1 or the upcoming 0.7.
Thanks for the quick response and sorry that I missed the other ticket. I'm not sure why I didn't see it before posting. I'll try your suggestion and report back the results.
I can confirm that your above instructions provide backwards compatibility at least in our fairly non-trivial project. Thank you.
Lets close this since this happened a long time ago.