corda/docs/source/cli-ux-guidelines.rst

.. highlight:: kotlin
.. raw:: html

   <script type="text/javascript" src="_static/jquery.js"></script>
   <script type="text/javascript" src="_static/codesets.js"></script>

CLI UX Guide
============

Command line options
--------------------

Command line utilities should use picocli (http://picocli.info) to provide a unified interface and follow the conventions in the picocli documentation, some of the more important of which are repeated below.

Option names
~~~~~~~~~~~~

* Options should be specified on the command line using a double dash, e.g. ``--parameter``.
* Options that consist of multiple words should be separated via hyphens e.g. ``--my-multiple-word-parameter-name``.

Short names
~~~~~~~~~~~

* Where possible a POSIX style short option should be provided for ease of use (see http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html#tag_12_02).

  * These should be prefixed with a single hyphen.
  * For example ``-V`` for ``--verbose``, ``-d`` for ``--dev-mode``.
  * Consider adding short options for commands that would be ran regularly as part of troubleshooting/operational processes.
  * Short options should not be used for commands that would be used just once, for example initialising/registration type tasks.

* The picocli interface allows combinations of options without parameters, for example, ```-v`` and ```-d`` can be combined as ``-vd``.

Positional parameters
~~~~~~~~~~~~~~~~~~~~~

* Parameters specified without an option should ideally all be part of a list.

  * For example, in ``java -jar test.jar file1 file2 file3``, the parameters file1, file2 and file3 should be a list of files that are all acted on together (e.g. a list of CorDapps).

* Avoid using positional parameters to mean different things, which involves someone remembering in which order things need to be specified.

  * For example, avoid ``java -jar test.jar configfile1 cordapp1 cordapp2`` where parameter 1 is the config file and any subsequent parameters are the CorDapps.
  * Use ``java -jar test.jar cordapp1 cordapp2 --config-file configfile1`` instead.

Standard options
~~~~~~~~~~~~~~~~

* A ``--help`` option should be provided which details all possible options with a brief description and any short name equivalents. A ``-h`` short option should also be provided.
* A ``--version`` option that should output the version number of the software. A ``-V`` short option should also be provided.
* A ``--logging-level`` option should be provided which specifies the logging level to be used in any logging files. Acceptable values should be ``DEBUG``, ``TRACE``, ``INFO``, ``WARN`` and ``ERROR``.
* ``--verbose`` and ``--log-to-console`` options should be provided (both equivalent) which specifies that logging output should be displayed in the console.
  A ``-v`` short option should also be provided.

Standard subcommands
~~~~~~~~~~~~~~~~~~~~

* An ``install-shell-extensions`` subcommand should be provided that creates and installs a bash completion file.

Defaults
~~~~~~~~

* Flags should have sensible defaults.
* Boolean flags should always default to false. Specifying the flag without a parameter should set it to true. For example ``--use-something` should be equal to ``--use-something=true`` and no option should be equal to ``--my-flag=false``.
* Do a bit of work to figure out reasonable defaults. Nobody likes having to set a dozen flags before the tool will cooperate.

Adding a new option
~~~~~~~~~~~~~~~~~~~

* Boolean options should start with is, has or with. For example, ``--is-cheesy``, ``--with-cheese``, ``--has-cheese-on``.
* Any new options must be documented in the docsite and via the ``--help`` screen.
* Never use acronyms in option names and try and make them as descriptive as possible.

Parameter stability
~~~~~~~~~~~~~~~~~~~

* Avoid removing parameters. If, for some reason, a parameter needs to be renamed, add a new parameter with the new name and deprecate the old parameter, or alternatively
keep both versions of the parameter. See :ref:`cli-ux-backwards-compatibility` for more information.


Notes for adding a new a command line application
-------------------------------------------------

The ``CordaCliWrapper`` base class
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The ``CordaCliWrapper`` base class from the ``cliutils`` module should be used as a base where practicable, this will provide a set of default options out of the box.
In order to use it, create a class containing your command line options using the syntax provided at (see the `picocli <https://picocli.info/>`_ website for more information)


.. container:: codeset

    .. sourcecode:: kotlin

        import net.corda.cliutils.ExitCodes
        import net.corda.cliutils.CordaCliWrapper

        class UsefulUtilityExitCodes: ExitCodes {
            companion object {
                val APPLICATION_SPECIFIC_ERROR_CODE: Int = 100
            }
        }

        class UsefulUtility : CordaCliWrapper(
            "useful-utility", // the alias to be used for this utility in bash. When install-shell-extensions is run
                              // you will be able to invoke this command by running <useful-utility --opts> from the command line
            "A command line utility that is super useful!" // A description of this utility to be displayed when --help is run
        ) {
            @Option(names = ["--extra-usefulness", "-e"], // A list of the different ways this option can be referenced
                    description = ["Use this option to add extra usefulness"] // Help description to be displayed for this option
            )
            private var extraUsefulness: Boolean = false // This default option will be shown in the help output

            override fun runProgram(): Int { // override this function to run the actual program
                try {
                    // do some stuff
                } catch (KnownException: ex) {
                    return UsefulUtilityExitCodes.APPLICATION_SPECIFIC_ERROR_CODE // return a special exit code for known exceptions
                }

                return UsefulUtilityExitCodes.SUCCESS // this is the exit code to be returned to the system inherited from the ExitCodes base class
            }
        }


Then in your ``main()`` method:

.. container:: codeset

    .. sourcecode:: kotlin

        import net.corda.cliutils.start

        fun main(args: Array<String>) {
            UsefulUtility().start(args)
        }



Application behavior
~~~~~~~~~~~~~~~~~~~~

* Set exit codes using exitProcess.

  * Zero means success.
  * Other numbers mean errors.

* Setting a unique error code (starting from 1) for each thing that can conceivably break makes your tool shell-scripting friendly.
* Make sure all exit codes are documented with recommended remedies where applicable.
* Your ``--help`` text or other docs should ideally include examples. Writing examples is also a good way to find out if your program requires a dozen flags to do anything.
* Don’t print logging output to the console unless the user requested it via a ``-–verbose`` flag (conventionally shortened to ``-v``). Logs should be either suppressed or saved to a text file during normal usage, except for errors, which are always OK to print.
* Don't print stack traces to the console. Stack traces can be added to logging files, but the user should see as meaningful error description as possible.

.. _cli-ux-backwards-compatibility:

Backwards Compatibility
-----------------------

Our commitment to API stability (See :doc:`api-scanner` for more information) extends to new versions of our CLI tools. Removing and renaming
parameters may cause existing scripts users may have written to fail, and should be avoided unless absolutely necessary.

Deprecating command line parameters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Command line parameters that are no longer necessary should be deprecated rather than removed. Picocli allows parameters to be hidden by use
of the ``hidden`` option, for example:

.. container:: codeset

    .. sourcecode:: kotlin

        import net.corda.cliutils.CordaCliWrapper

        class UsefulUtility : CordaCliWrapper("useful-utility", "A command line utility that is super useful!") {
            @Option(names = ["--no-longer-useful", "-u"],
                    hidden = true,
                    description = ["The option is no longer useful. Don't show it in the help output."]
            )
            private var noLongerUseful: Boolean = false

            override fun runProgram(): Int {
                if (noLongerUseful) // print a warning to the log to let the user know the option has been deprecated
                    logger.warn("The --no-longer-useful option is deprecated, please use the --alternatively-useful option instead")
                // do some stuff
                return UsefulUtilityExitCodes.SUCCESS
            }
        }

This will cause the option to still be usable, but means it won't be shown when ``--help`` is called. As a result, existing scripts dependent
on the parameter will still run, but new users will be directed to the replacement.

Changing the type of existing command line parameters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Don't change the type of an existing command line parameter if that change would not be backwards compatible. For example, adding a
value to an enumeration based parameter would be fine, but removing one would not. Instead of changing the type, consider adding a new parameter,
deprecating the old parameter as described above, and redirecting inputs from the old parameter to the new parameter internally.

Testing backwards compatibility
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When adding a new command line tool, a backwards compatibility test should be created by adding the ``test-cli`` as a test dependency of your project
and then creating a test class that extends ``CliBackwardsCompatibleTest`` for the class, like so:

.. container:: codeset

    .. sourcecode:: kotlin

        import net.corda.testing.CliBackwardsCompatibleTest

        class UsefulUtilityBackwardsCompatibleTest : CliBackwardsCompatibleTest(UsefulUtility::class.java)

The test will search for a YAML file on the class path named ``<fully.qualified.class.name>.yml`` which details the names, types and possible
options of parameters, and compares it to the options of the current class to make sure they are compatible.

In order to generate the file, create and run the test for your application. The test will fail, but the test output
will contain the YAML for the current state of the tool. This can be copied and then pasted into a correctly named ``.yml``
file in the resources directory of the project.

Release process
~~~~~~~~~~~~~~~

As part of the release process, the release manager should regenerate the YAML files for each command line tool by following the following steps:

* Check out the release branch
* Delete the ``<fully.qualified.tool.name>.yml`` file for the tool
* Re-run the backwards compatibility test for the tool
* Copy the resulting YAML from the test output
* Check out the master branch
* Replace the text in ``<fully.qualified.tool.name>.yml`` with the text generated on the release branch