search

ahrefs / atd

Static types for JSON APIs
Other
308 stars 53 forks source link

List of breaking features for major version 3.0.0 #369

Open mjambon opened 8 months ago

mjambon commented 8 months ago

This page is for keeping a list of desirable simple changes that break compatibility with past versions of the atd tools:

(1) atdgen: emit standard JSON by default. The -j-std option would become superfluous. (2) (maybe) atdgen: eliminate the ability to output nonstandard JSON (that needed to be turned off with -j-std). (3) (maybe) atdgen: eliminate the ability to read nonstandard JSON. (4) ...

Khady commented 8 months ago

(maybe) atdgen: eliminate the ability to output nonstandard JSON (that needed to be turned off with -j-std). (maybe) atdgen: eliminate the ability to read nonstandard JSON.

Those would be a big break for people who store json emitted by atd in a db or any other kind of long term storage.

mjambon commented 8 months ago

(2) (maybe) atdgen: eliminate the ability to output nonstandard JSON (that needed to be turned off with -j-std). (3) (maybe) atdgen: eliminate the ability to read nonstandard JSON.

Those would be a big break for people who store json emitted by atd in a db or any other kind of long term storage.

(2) is safe because the generated code can read both formats anyway unless some other nonstandard JSON parser exists out there and expects the nonstandard format (<A> or <B:42>) and doesn't support the standard representation ("A" or ["B", 42]). I doubt such a thing exists.

(3) as you're pointing out, would break things for some people. I suspect it would affect mostly people who didn't realize the JSON wasn't standard and went with the default command line.

I suggest: (1): implement in atd 3.0 (2): implement in atd 3.0 (3): "deprecate" in atd 3.0 (not sure how: maybe require a flag like --deprecated-tolerate-atd-json-extensions)

Note that if we end up implementing atdml, it would not support this nonstandard JSON. When this happens, I'd like to stop adding features to atdgen (such as module support) and we'd do minimal maintenance so it remains usable for a while. Users who don't like this plan should chime in on the ticket https://github.com/ahrefs/atd/issues/313, especially if performance of JSON reading and writing is critical in their application (expect about a 3x slowdown with atdml).