@redis/core-team please review / approve / comment.

@oranagra @guybe7 Note: there are some comments in the documentation which, once resolved, should probably be reflected here.

Removed the "random" and "sort_for_script" flags. They are now command tips. (this isn't affecting redis behavior since Remove EVAL script verbatim replication, propagation, and deterministic execution logic #9812, but could affect some client application that's relying on COMMAND command flags)

sort_for_script is nonsense now, but as you said random may be used by some clients, so I think maybe it's better to keep random flag avoid breaking clients.

@soloestoy i think both can be used by some applications or frameworks (to know if the same command on the same data set can produce different results).
The old command flags is the wrong place for these, so i'd like to move them.
The question is indeed the breaking change, if there are many that may rely on them, we may consider to keep them where they where, but i'm estimating that there are not many who use these (if any), and considering all the other changes we did to the flags (including re-assigning these two tags differently on some commands), i think we can afford to move them.
are you aware of any app / framework that actually uses these today?

@oranagra not sure if I can find some real use cases, but I'm a little confused with what you said, I remember the original intention of the refactoring of COMMAND reply and specs, is we wanna let our code can be self-documented, and let clients get key position and flags correctly and easily. So, I think at the beginning of the refactoring we have the assumption that some clients and frameworks have already relied on COMMAND reply. And now IIUC seems you mean no one are using it, looks like contradictory.

i'm sure some parts of the old COMMAND command are widely used (like firstkey, lastkey), and these are kept in a backwards compatible manner (although we would have rather delete them).

other parts have changes which are just the reality (e.g. we could have delete some flag if it no longer makes sense, and the commands that used it can no longer be flagged that way). i don't think there are such changes in the flags, but there could be.
i.e. consider the mislabel of HGETALL.

lastly, in some cases we introduce potentially breaking changes, in order to solve bugs or reduce tech debt (like #10095).

so it's a compromise between trying not to break anything that's being used, and fixing things to be better for future generations.

We discussed this in a core-team meeting and concluded that the RANDOM and BLOCKING flags should move from the tip to the command flags.

These are arguably flags that describe the redis command (what redis does), and not just how clients should handle it.
It's true that redis doesn't currently uses them, but maybe it will some day.

We should let modules define both flags.

Note that the RANDOM flag was there in the past, moving it could be considered a blocking change (probably not affecting many), but we're arguing that it may be better to keep it there anyway.

i've pushed that change (didn't update the top comment yet).
i now realize that sort_for_script already existed in the COMMAND command flags, so i'm not certain if we wanna keep random there, or move it to be RANDOM_OUTPUT in the tips (revert my last commit).
would like some feedback.

@soloestoy please respond ^^.
considering that both random and sort_for_script where exposed in the past, and we do see value in still exposing these (at least tips, so some frameworks can have that info), i find it odd to keep one in flags and one in tips.

i agree that redis may some day decide to rely on the BLOCKING flag, but i'm not sure about the RANDOM flag.
maybe i should revert my last commit and let them all be tips?
i do not think removing either of these from the flags is a big breaking change (just a flag, and unlike the movablekeys flag, it's not a highly used one)

the reasoning for keeping random and removing sort_for_script is the assumption that random is used and sort_for_script isn't.

if indeed we are worried about BC we should have all three (random, random_order, and blocking) as flags. side note: if blocking is a flag, the ACL categories can be implicit

if we don't think BC is an issues here I think that blocking should still be a flag and that random and random_order should be tips

if we don't think BC is an issues here I think that blocking should still be a flag and that random and random_order should be tips

i'm leaning towards that. i don't think there are many (or any) users who used this flag, and i don't think it belongs in the flags field.

Personally, fwiw, I'm unaware of any clients/frameworks that rely on these flags, so backward compatibility, in this case, is less than crucial imo.

Firstly I think we can analyze why clients need to use command flags random and sort_for_script.

1. about random:

    * random:      Random command. Command is not deterministic, that is, the same
    *              command with the same arguments, with the same key space, may
    *              have different results. For instance SPOP and RANDOMKEY are
    *              two random commands.
   

   From the comments I cannot get a conclusion if some clients are using it, so I'd like keep it as a flag, avoid breaking change.

2. about sort_for_script:

    * to-sort:     Sort command output array if called from script, so that the
    *              output is deterministic. When this flag is used (not always
    *              possible), then the "random" flag is not needed.
   

   This flag is only used in Lua script, it's an internal flag, I think no one is using it. And now Lua script doesn't need this flag, so remove it won't break anything even some clients reply on it (maybe some clients refused commands with sort_for_script? If so, remove it is OK, since these commands don't need sort now).

Beside whether it is a breaking change or not, I think random is an attribute of a redis command just like BLOCKING WRITE READ etc., so I prefer keep random as a flag, and remove sort_for_script.

decisions from discussion with @yossigo and @oranagra :

1. remove blocking_keyword - it's too complex to avoid false positives. in the cases of XREAD, the client will hardcode search for BLOCK. module command should avoid this (i.e. have a command potentially block just by providing a keyword)
2. blocking is a flag
3. random_order_output (past: sort_for_script) is a tip
4. nondeterministic_output(past: random) is a tip
5. rename non_trivial -> special
6. add all_nodes, change all_shards -> all_masters
7. rename few_shards -> multi_shards
8. rename reply_policy -> response_policy

Adding to @guybe7's note above, I'll clarify what was the rationale behind some of these decisions:

• We view flags as something that is used internally by Redis, whereas command tips only describe intended client interaction (and as such may be more loosely defined in some cases, likes modules).
• BLOCKING is something that is useful to know at the server side, hence, should be a flag.
• random and to-sort are not used (anymore) by Redis, but may be used by clients in rare esoteric cases so:
  1. We don't want to completely remove them.
  2. We do wish to choose better names and move them to their right place (tips).
  3. To achieve [ii] we're willing to live with a minor backwards compatibility breakage (minor because of [i], and because the fix on the client side is very straightforward).

i prefer nondeterministic_output_order instead of random_order_output
i think we agreed to use all_shards (not all_master, the doc will say this means "masters")
maybe multi_shard instead of multi_shards?

The last few commits handle #10104 (comment)

ALL_NODES commands:
CONFIG SET

ALL_MASTERS commands:
SCRIPT KILL
SCRIPT FLUSH
SCRIPT EXISTS
SCRIPT LOAD
FUNCTION FLUSH
FUNCTION DELETE
FUNCTION RESTORE
FUNCTION LOAD
FUNCTION STATS
FUNCTION KILL
SLOWLOG RESET
SLOWLOG LEN
SLOWLOG GET
DBSIZE
KEYS
WAIT
RANDOMKEY
PING
FLUSHDB
FLUSHALL
INFO

MULTI_SHARD commands:
EXISTS
MSET
TOUCH
MGET
UNLINK
DEL

maybe SCRIPT LOAD and SCRIPT FLUSH should be ALL_NODES?