v1.0.0.0 planning

[bergmark]

in suggested merge order:

• TaggedObject encoding for Nullary constructor includes "contents" #300 via TaggedObject encoding for Nullary constructor does not have "contents" field #307 Removing contents field for nullary constructors
• Investigate whether TaggedObject encoding for Nullary constructor does not have "contents" field #307 is/can be made a non-breaking change (no since the encode output changes, but "contents" : [] is luckily still accepted when parsing)
• Fix a bug with generics and single-field records #366 Fix a bug with generics and single-field records
• ToJSON1 & FromJSON1 #352 via Add lifted typeclasses and some instances #381 Lifted type classes
• overlapping instances for [Char] #351 via List instance #382 stop using overlapping instances for strings
• Generalise FromJSON (Map k v) instances #289 via Even more general map serialising #341 Generalized map serialization
• Higherkinded special strings #391 Modify higher kinded typeclasses from Add lifted typeclasses and some instances #381
• Invalid JSON generated by genericToEncoding #387 Fix omitNothingFields + genericToEncoding via Fix issue #387 with encoding using omitNothingFields #394
• JSONPath isn't tracked in autoderived instances #357 JSONPath isn't tracked in autoderived instances (TH & generics) via Track JSONPath in autoderived parsers. Fixes #357 #398
• FromJSON/ToJSON instances in haddocks #375 Improve haddocks by not using orphan instances
• Generics for Higher kinded type classes via Generics and TH support for lifted typeclasses #414 and Fromjson1 th generics backup no orphans #415
• Add documentation on how to use/write ToJSONKey (etc) instances. @andrewthad
• Finalise encoding refactoring @phadej
• Add notes on all these checklist items to the changelog @bergmark
• Write tests for lifted typeclasses and their generic/th derivations @phadej
• Do some stackage/Silk testing @bergmark
• Fix recently added TODOs
• Do not truncate Integral values #317 Do not accept and truncate floats to integrals

Please give feedback if I missed something!

[bergmark]

@andrewthad @phadej should we start by merging the lifted type classes next?

[andrewthad]

Yeah, I think that that one is the best place to start since it was rebased on top of master like a week ago.

[RyanGlScott]

We should probably add generics/TH support for the lifted typeclasses to this list. I haven't made an issue for it, since I was hoping it could be a part of #352, but I dropped the ball.

[andrewthad]

@RyanGlScott If I understand correctly, the generics/TH support is a non-breaking change. Even if it were added after the 0.12 release, I think it would only require bumping minor version. If it's something that you can do in under a week, I don't think that anyone would object to you adding it for the 0.12 release though.

[andrewthad]

Also @bergmark, I'd still like to redo the module merge from #375 to eliminate orphan instances. I think that now is probably a good time to do that. Let me know if you agree and I'll do it.

[andrewthad]

Nevermind, I just noticed #412

[andrewthad]

Down to one final checkbox. I'll add the docs for using ToJSONKey and friends.

[bergmark]

before i added another one ;-) But thanks!

I'll do the changelog later.

[phadej]

I'd like to finalise my Encoding related refactoring and write tests to lifted typeclasses and their generic/th derivations

[phadej]

Few more points:

write Key instance to at least numeric and datetime types, then the ones I'd personally need would be covered. I can do it while making Encoding related refactorings, as they would be easy to add next to ToJSON and FromJSON instances.

I'd like to see what needed to be exported to write instance for InsOrdHashMap using new aeson's ToJSONKey and FromJSONKey functionality

[bergmark]

@andrewthad Did you consider error messages for FromJSONKey? I suppose this wasn't needed before. It would be super nice if we had JSONPath error messages here as well

[andrewthad]

I hadn't considered that. I haven't really worked with the JSONPath parts of aeson before, so I don't know how they work. Currently, we can get errors like this:

>>> eitherDecode "{\"hey\": {\"foo\": \"not_number\"}}" :: Either String (M.Map Text (M.Map Text Int))
Left "Error in $.hey.foo: expected Int, encountered String"

Which is good. If we instead expect an Int key, we get:

>>> eitherDecode "{\"hey\": {\"foo\": \"ht\"}}" :: Either String (M.Map Text (M.Map Int Int))
Left "Error in $.hey: input does not start with a digit"

What error would we expect instead?

[phadej]

@andrewthad @bergmark #423

[phadej]

Bikeshedding: should 0.12 be actually 1. There are so many changes which even are kind-of backwards compatible but not really.

[andrewthad]

I actually had the same thought yesterday. Even though the changes in this release probably cause very little breakage, they are some pretty substantial changes. Much bigger than anything that's happened since at least as far back as the 0.6 release. I think calling it a 1.0 release would be appropriate.

[tolysz]

The new trend would be to call it 2016.0

[bergmark]

Sure v1 sounds good.

[andrewthad]

Just put up some improved docs for FromJSONKey: #428

[phadej]

tried to port insert-ordered-containers: seems to work, yet we have less helpers for building Values then Encodings https://github.com/phadej/insert-ordered-containers/pull/5/files

[phadej]

Should #437 be added to the list?

[phadej]

Recently added TODOs:

• toJSONKeyTextEnc :: (a -> Encoding' Text) -> ToJSONKeyFunction a (analogue to toJsonKeyText) should this be exported?
• also toJSONKeyTextEnc: dropAround is also used in stringEncoding, which is unfortunate atm. I don't have any idea how fix this without breaking changes. But I don't think it's very important.
• Builder.hs: Extend documentation with references to source code in blaze-html or aeson that uses this function. @RyanGlScott ?
• TODOs for Do not truncate Integral values #317

[RyanGlScott]

@phadej That comment was copied wholesale from text, so it wasn't meant to reflect something that actually needed to be done in aeson. It can be removed if you desire.

[phadej]

Write tests for lifted typeclasses and their generic/th derivations is done by #439.

Is there something we can help to make aeson-1.0.0.0 land on Hackage?

[bergmark]

I'm planning to sit down this weekend and see if I can more stuff ready.

• I'm not sure if we should merge improve object/jstring parser #452 before, I'd still like to see benchmarks result and a haskell version of the module. It could be added later but it feels a bit sketchy to hide it in a minor version.
• Are INLINE pragmas worth the compilation time? #424 bothers me, but perhaps putting -O2 under a manual flag is good enough.

[bergmark]

@phadej I'm looking at the new Encoding modules. For example (><) and (>*<) are only exported from the internal module. Are they redundant when writing instances?

[phadej]

Yes, they are. They are used to implement high-level combinators.

[bergmark]

Does it then make sense to not export those at all and change all instances to only use the public API?

[phadej]

@bergmark IIRC template haskell derivation uses them. It can be changes not to use them, but i'm not sure it's worth the effort atm.

[bergmark]

A lot of code uses the internals.

$ git grep '>\*<' Data/Aeson/Types/ToJSON.hs  | wc -l
     110

I imagine that people will look at existing instances for inspiration so it'd be nice to show how the library is supposed to be used there.

[phadej]

@bergmark those are the tuples, aren't they?

[phadej]

Could be "easily" redone, as code is generated...

[bergmark]

yeah i'm working on it

[winterland1989]

@bergmark I can provide benchmark result, just let me know which benchmark you wanna run, i'll try to give it a go. The result for benchmarks in master has already upload in #452 .

The c code is not so easily ported to haskell though, it's similar to the decoding part in @text@, looping into a CString is tricky in haskell.

[phadej]

@bergmark note the QuickCheck pull requests. IMHO it makes sense to bump bounds for aeson-0.11 also.

Would help migrating...

[phadej]

Great, thanks for the release!