So... I'm in the process of implementing RESP3 client changes in SE.Redis; @slorello89 kindly commented on breaking API changes, which ... confused me, but after investigating: they're right; so far I have identified only two:

• ZRANGE (result pairs become jaggified)
• XREAD (drops a level of nesting between the array and map representation)

I do not know for sure that this list is exhaustive.

In both cases, the shape of the returned data changes in a non-trivial (i.e. calling-code-breaking) way based on whether the connection is RESP2 vs RESP3. What makes it worse is:

• it is completely undocumented on the command reference
• it is completely undocumented on the protocol specification
• if we look at the ZRANGE change, this major API change was not even called out or discussed on the PR
• oh, and it isn't even just "on RESP3" - it is is "on RESP3 and some server version > 6.2.6" (I haven't found the exact version, sorry)
• (I haven't tracked the XREAD change; please feel free to do so; nor can I reasonably find every such change, unless I stumble over them in my test rigs)

I don't want to beat about the bush; this is bad. Very bad. Like: jaw-droppingly hostile towards consumers; I think there have been multiple significant failings here - and please understand: I get it, these things happen - the point of this post is this cannot keep happening.

In order:

1. The returned data shape is PART OF THE API; these major API breaks SHOULD NOT HAVE HAPPENED
2. Or if they did happen, it should have been with an opt-in argument
3. Or at least, in a "major"
4. And it must be clearly documented in the command specification
5. And it should have been properly discussed in the PR when the change was made (ideally with the result "it doesn't happen")

From a client library angle, I now need to know a lot of variations (server version, protocol, etc) - and they aren't documented.

I'm looking for some help from Redis folks here; hopefully some positive outcomes; IMO:

1. all such API breaks should be clearly documented on the relevant command pages, including protocol and server version matrix
2. all such API breaks should be collated somewhere, including protocol and server version matrix
3. please please please don't make any more of these! (changing from an interleaved "array" to "map": fine, no problem! but changing the nesting layout or jaggifying an array? nononononononono)

(if 1/2 sound like a lot of work: yes! yes, it is - and right now you're pushing that work to all the users and library maintainers, probably to be found the hard way)

Help me Redis-Kenobi; you're my only hope!