TL;DR;
The aim of this JIRA is to start unification of an issue handling in CLI commands.
Details:
Currently there is a discrepancy between returned error codes if an issue occurred during execution. It depends on the fact whether the CLI command is implemented as @CLIMethod or extending hudson.cli.CLICommand class.
@CLIMethod usually returns 1 in the case an issue occurred, similar situation in hudson.cli.CLICommand returns -1 to the shell.
There is an ongoing effort to extract all CLI commands from the Core to CLI (see JENKINS-22969), so the discrepancy should be removed shortly and consistent error code definition should be set-up on one place only - in hudson.cli.CLICommand.
Currently we should use this semantic in CLI:
- 0 means All right
- -1 means An error occurred
Technically anything else than zero means an issue occurred. Later we can use more precisely defined error codes for the different issues if useful.
Update 07-Jan-2016 (WIP):
TODO
- Refactor core commands to use correct exception classes
- Update javadoc for CLICommand#run
- Unify the handling in CLIRegisterer
Proposed a new unified scheme of exception raising, handling, reporting and error code returning:
Update 12-Feb-2016: - Exception -> Throwable
Exception name | Meaning | Correct usage | Incorrect usage | Processing | Return code |
---|---|---|---|---|---|
CmdLineException | Wrong parameter, input value can't be decoded etc. |
CommandDuringBuild.java |
|
|
2 |
IllegalStateException | Can't continue due to an incorrect state of Jenkins instance, job, build etc. |
CommandDuringBuild.java comes from Jenkins.getActiveInstance() |
none |
|
4 |
IllegalArgumentException | Can't continue due to wrong input parameter (job doesn't exist etc.) |
CopyJobCommand.java |
|
|
3 |
AbortException | Can't continue due to an other (rare) issue Note: Current usage of this exception is wrong, usually there should be IllegalState or CmdLine exception raised instead of this |
none |
|
|
5 |
AccessDeniedException | Not sufficent rights for requested action | comes from checkPermission() | none |
|
6 |
BadCredentialsException | Bad credentials provided via the CLI | N/A | N/A |
|
7 |
Throwable |
Any unknown issue occurred, just to report it for the record | N/A | N/A |
|
1 |
- is blocking
-
JENKINS-31417 Extract connect-node CLI command from Core to CLI
-
- Resolved
-
-
JENKINS-31847 Extract clear-queue CLI command from Core to CLI
-
- Resolved
-
-
JENKINS-31900 Extract reload-configuration CLI command from Core to CLI
-
- Resolved
-
-
JENKINS-32535 Improve test coverage of CLI commands 'add-job-to-view' and 'remove-job-from-view'
-
- Resolved
-
-
JENKINS-32684 Improve test coverage of CLI command 'console'
-
- Resolved
-
-
JENKINS-32777 Improve test coverage of CLI command 'delete-builds'
-
- Resolved
-
I suggest to keep the cases when command is putting Jenkins into some state (computer offline, jenkins quieting down, job in view, etc.) while it already is in such state aside for now as I would like to see those idempotent and therefore return 0. (Unless we want to squeeze such change into this PR).
I fail to come up with a definition of foreseeable failure class. Consider there is a client that calls Jenkins CLI internally, how would handling of such problems differ?