Migration guide 1.5 -> 2.0

[andreasabel]

The changelog isn't explicit about how to migrate from aeson-1.5 to -2.0.
Please add a migration guide with the most common fixes needed.

[phadej]

it's a changelog, not a migration guide. You can contribute your observations here.

You can pick ideas from

• haskell-github/github@dd3dfbc
• phadej/aeson-optics@ff31ca0
• clash-lang/clash-compiler@55ec75d

In summary, change import qualified Data.HashMap.Strict as HM to import qualified Data.Aeson.KeyMap as KM. Apply CPP to your liking.

[andreasabel]

Here is one more: agda/agda@8037346

[tfausak]

So essentially the official advice is "good luck"? That's disappointing.

Here's my summary of the changes and what you'll need to do to support them:

• Change Object to use an opaque KeyMap interface #866: Introduced the Data.Aeson.KeyMap.KeyMap type and replaced any HashMaps with KeyMaps. If your project depends on Aeson's Object type being a HashMap, then you'll have to update your code to use the new KeyMap instead. Since the interfaces are similar, usually you can use CPP to import either Data.HashMap.Strict or Data.Aeson.KeyMap depending on the version of Aeson.

• Data.Aeson.Key #868: Introduced the Data.Aeson.Key.Key type and replaced any Text keys with Keys. If your project depends on keys being Text, for example if you use the pair function with something other than an overloaded string, you'll have to update your code to use the new Key representation instead. Since Key's interface is minimal, you'll probably have to introduce fromKey and toKey functions that are defined with CPP so that you can continue to work with Text values and convert to Keys as late as possible.

• Drop GHC-7 support #872: Dropped support for GHC 7.10 and earlier. If you use an affected version of GHC, you can't upgrade to Aeson 2.

• Add ordered keymap option #871: Added the ordered-keymap flag. When set, this flag changes the representation of KeyMap from HashMap to Map. This is the change that will prevent a hash flood attack. The flag is not enabled by default with Aeson 2.0.0.0, but it is enabled by default with version 2.0.1.0. If it's important that you avoid hash flood attacks, you should explicitly enable this flag!

• Change +inf/-inf :: Double/Float serialization #873: Changed representation of infinite floating point values. Previously they were represented as null, but now they are "+inf" for positive infinity and "-inf" for negative infinity. This probably does not require any changes in your code, but be aware that JSON generated by Aeson may be different than before when it includes infinite floating point values.

• Accept all values in FromJSON () and FromJSON (Proxy tag) #874: Changed FromJSON instances for () and Proxy a to accept any value. Previously they only accepted an empty array. This probably does not require any changes in your code, but be aware that JSON parsed by Aeson will now accept other values for these types.

• If you do anything non-trivial with Aeson, you're probably going to need CPP (or something equivalent to it) in order to support these changes.

• Since this is a super major version upgrade (from 1.5.x.y to 2.0.x.y), be sure to get your version bounds correct! Don't do >= 1.5 && < 2.1, which would allow a hypothetical version 1.6, which would have breaking changes. Instead do >= 1.5 && < 1.6 || >= 2.0 && < 2.1, or something equivalent to it like ^>= 1.5 || ^>= 2.0.

[Bodigrim]

So essentially the official advice is "good luck"? That's disappointing.

Could we please stop bashing maintainers for doing free work? @phadej fixed the vulnerability (together with @Boarders), made a release, and marked this issue as "help wanted". I'm not sure what exactly is disappointing here.

[googleson78]

While I do strongly agree with the sentiment of "let's not bash people doing free labour", I'd also like to express thanks to @tfausak for the write-up. This was not expressible in a clear way with emojis, so I wrote a comment instead.

[frasertweedale]

Here's my diff for jose: frasertweedale/hs-jose@ffc0cde

Apart from updating Text -> Key there are some places where I filter maps by key, which required a bit of explicit converting between Map Text <-> KeyMap (these have the same representation with +ordered-keymap, so should be zero runtime overhead) Overall it was a non-trivial but definitely not painful update.

[googleson78]

So it might be worth extending the KeyMap interface with a filtering mechanism?

[frasertweedale]

@googleson78 not necessarily. How to filter efficiently can depend on the underlying representation (e.g. if you want to keep/drop keys in an existing Set or HashSet).