CLI "style"

[kitsonk]

Enhancement

We have some inconsistent styles in dojo that we should agree to a "style guide" for terms and explaining things and align things to that style.

For example, dojo help outputs this:

Commands:
  build    create a build of your application
  test     this command will implicitly build your application and then run
           tests against that build
  create   Scaffolds a new app
  eject    disconnect your project from dojo cli commands
  version  provides version information for all installed commands and the cli
           itself.

Options:
  -h, --help  Show help                                                [boolean]

For more information on any of these commands just run them with '-h'.

e.g. 'dojo build -h' will give you the help for the 'build' group of commands.

We have a mixture of capitalisation mis-alignment and whether or not we use periods/full-stops.

Also, in commands, we should have a style guide of how we use colours and what the colours mean and what we would expect output for a command to look like. Right now it feels rather minimal and somewhat inconsistent.

[bryanforbes]

Proposal for CLI string style guide:

• All descriptions MUST start with a capitalized word and MUST NOT end with a period.
• Command descriptions SHOULD start with an imperative verb (ex. "Create a build of your application").
• Descriptions of boolean options that modify the behavior of their command SHOULD start with an imperative verb (ex. "Generate package information useful for debugging").
• Descriptions of all other options SHOULD start with either a definite or an indefinite article (ex. "The path to a custom element descriptor factory"). A definite article is preferred.

Following the proposed style guide, the output above would be changed to the following:

Commands:
  build    Create a build of your application
  test     Build and test your application
  create   Scaffold a new application
  eject    Disconnect your project from dojo cli commands
  version  Print version information for all installed commands and the cli
           itself

Options:
  -h, --help  Show help                                                [boolean]

For more information on any of these commands just run them with '-h'.

e.g. 'dojo build -h' will give you the help for the 'build' group of commands.

The output of dojo build help would be changed to:

Commands:
  webpack  Create a build of your application

Default Command Options ('webpack')
  -w, --watch                   Watch and serve
  -p, --port                    The port on which to serve files when using
                                --watch                                 [number]
  -t, --with-tests              Build tests as well as sources
  --locale                      The default locale for the application  [string]
  --supportedLocales            The locales supported by the application [array]
  --messageBundles              The message bundles to include in the build
                                                                         [array]
  --element                     The path to a custom element descriptor factory
                                                                        [string]
  --elementPrefix               The output file for custom element      [string]
  --debug                       Generate package information useful for
                                debugging                              [boolean]
  --disableLazyWidgetDetection  Disable lazy widget loading detection  [boolean]

Options:
  -h, --help  Show help                                                [boolean]

[tomdye]

I personally think that all descriptions should end with a full stop. Please bear in mind that some of the output is controlled by yargs and not by ourselves.

[bryanforbes]

Here's what the output would look like with full stops:

Commands:
  build    Create a build of your application.
  create   Scaffold a new application.
  test     Build and test your application.
  eject    Disconnect your project from dojo cli commands.
  version  Print version information for the cli and all installed commands.

Commands:
  webpack  Create a build of your application.

Default Command Options ('webpack')
  -w, --watch                   Watch and serve
  -p, --port                    The port on which to serve files when using
                                --watch.                                [number]
  -t, --with-tests              Build tests as well as sources.
  --locale                      The default locale for the application. [string]
  --supportedLocales            The locales supported by the application.[array]
  --messageBundles              The message bundles to include in the build.
                                                                         [array]
  --element                     The path to a custom element descriptor factory.
                                                                        [string]
  --elementPrefix               The output file for custom element.     [string]
  --debug                       Generate package information useful for
                                debugging.                             [boolean]
  --disableLazyWidgetDetection  Disable lazy widget loading detection. [boolean]

[bryanforbes]

After playing with the different options, here's the updated proposal:

• All descriptions MUST start with a capitalized word and MUST end with a period.
• Command descriptions SHOULD start with an imperative verb (ex. "Create a build of your application").
• Descriptions of boolean options that modify the behavior of their command SHOULD start with an imperative verb (ex. "Generate package information useful for debugging").
• Descriptions of all other options SHOULD start with either a definite or an indefinite article (ex. "The path to a custom element descriptor factory"). A definite article is preferred.

Following the proposed style guide, the output for dojo help would be:

Commands:
  build    Create a build of your application.
  create   Scaffold a new application.
  test     Build and test your application.
  eject    Disconnect your project from dojo cli commands.
  version  Print version information for the cli and all installed commands.

Options:
  -h, --help  Show help.                                               [boolean]

The output of dojo build help would be:

Commands:
  webpack  Create a build of your application.

Default Command Options ('webpack')
  -w, --watch                   Watch and serve.
  -p, --port                    The port on which to serve files when using
                                --watch.                                [number]
  -t, --with-tests              Build tests as well as sources.
  --locale                      The default locale for the application. [string]
  --supportedLocales            The locales supported by the application.[array]
  --messageBundles              The message bundles to include in the build.
                                                                         [array]
  --element                     The path to a custom element descriptor factory.
                                                                        [string]
  --elementPrefix               The output file for custom element.     [string]
  --debug                       Generate package information useful for
                                debugging.                             [boolean]
  --disableLazyWidgetDetection  Disable lazy widget loading detection. [boolean]

Options:
  -h, --help  Show help.                                               [boolean]

[kitsonk]

We should do one more pass at this.

[agubler]

This should have been resolved by the new cli help/command renderer #229