Guidelines for subcommands and/or numerics

[Zarthus]

IRCv3 is rather vague on how create new subcommand responses and add new numerics, guidelines and/or style guides on how to handle this would help ending up with inconsistencies in the future

Small sample:

A command /TEST returns the subcommand response.

TEST ERR SOME_ERROR

Guidelines could exist for "the error should always be ERR, not ERROR", "SOME_ERROR" has to be in all caps, and "on success just return the result."

In a similar vein, we don't know whether we're supposed to pull numerics out of our arse either.

[prawnsalad]

Just for some context from the client dev perspective:

[prawnsalad] one of the big issues i have with client dev is that when i send a command, most the times it may get a response. and that response may be one of any other responses shared with other commands, making it difficult to guess if the returned numeric is associated to the context im in or something else
[...]
[prawnsalad] ideally, for any command created, it should be i send command X, and i expect a specific response for command X unless a response is never needed. error, ack, or response, just so that the client isnt sat there waiting for something that may or may not actually happen

[ghost]

A standard specification for how errors are defined and returned should exist. Custom numerics are limited in number, hard to track, and non-intuitive. The ability for command specifications to define reply codes by name (ACCESS_DENIED, CMD_INVALID, etc...) would allow for clients to better handle replies. Clients supporting the extension / capability / command would be required to handle each supported reply message.

The reply could be returned as a sub-command. Expanding on and generalizing @Zarthus's idea, a standard server reply in the format :nick!ident@host COMMAND REPLY_TYPE :REPLY_CODE accounts for both identification of the source command as well as the specific reply code. See ircv3/ircv3-specifications#292 for example implementation.

For instances where the same command may be sent multiple times, draft/labeled-replies could be implemented into the command, providing for identification of the specific command instance sent to the server (@label=ID COMMAND PARAMETERS) and it's specific reply (@label=ID :nick!ident@host COMMAND REPLY_TYPE :REPLY_CODE).

In a similar vein, we don't know whether we're supposed to pull numerics out of our arse either.

Likewise, how these replies are defined should be addressed. Are reply types and/or codes standard or custom? Are types standard with custom codes? If standardized, what is the process for defining a new reply and introducing it into the spec.

[DanielOaks]

Made ircv3/ircv3-specifications#357 in an attempt to start resolving this on the making new error responses side at least.