New Zowe conformance criteria suggestion - CLI exit codes

[plavjanik]

CLI exit codes

Situation

While working with different CLI plug-ins, there are inconsistencies in setting exit (return) codes of the CLI command.

Most CLI commands do a good job and set the exit code to 0 when the action that the command does (exit code of zowe zos-jobs submit represents the success of the job submission action - not the success of the execution, exit code of zowe zos-files upload represents the success of the download actions). Exit code 1 is set when the action fails (the job was not submitted or file upload failed).

But there are CLI plugins that do not set the exit code, so it is 0 no matter what goes wrong. That prevents the CLI command to be used in a script or other automation.

Some plug-ins have occasional problems e.g. https://github.com/zowe/zowe-cli/issues/1299 and those can be solved in a way that does not bring a breaking change by providing a new parameter to enable desired behavior in cases when the original behavior is already expected by some users.

Another inconsistency is that some CLI plug-ins return code that represents the success of the invocation of the action and not the action itself. In such a case, the command typically returns 0 unless there is a connection problem. For example check command returns 0 no matter if the checked object was valid or not but if the check has been performed no matter its result. But a typical user would expect that the code represents the result of the check.

Suggestion

Add the following CLI conformance criteria like:

CLI commands need to return the exit code. The value 0 of the code represents the success of the action that the command does (not just the success of calling an internal API). Value higher than 0, typically 1 is used when the action fails. Commands are allowed to use more values if it is necessary to differentiate them. If the existing CLI command does not conform to these criteria and it was done intentionally, it needs to provide an option to provide conformant behavior without breaking the existing behavior.

[balhar-jakub]

@zFernand0 This sounds like mostly CLI Squad related topic. Can I transfer it to your repository?

[github-actions[bot]]

Thank you for raising this enhancement request. The community has 90 days to vote on it. If the enhancement receives at least 5 upvotes, it is added to our development backlog. If it receives fewer votes, the issue is closed.

[adam-wolfe]

Moving to in progress so we discuss this as a conformance best practice in the next stand up.

[adam-wolfe]

May consider this as a v3 conformance requirement.

[adam-wolfe]

As a note for when we review this for V4, we added a new conformance "best practice" for Zowe V3 that commands should provide exit codes according to some logic. For V4, we should make this a requirement (not just a best practice).