openstack team mailing list archive

[Doug Hellmann <doug.hellmann@xxxxxxxxxxxxx>]

On Mon, Apr 30, 2012 at 12:13 PM, Adam Spiers <aspiers@xxxxxxxx> wrote:

> Dean Troyer (dtroyer@xxxxxxxxx) wrote:
> > One of the first things to do is to find out who is interested in
> > contributing to this project.and hopefully coordinating some of the
> > work with the other emerging project-specific clients.  Send me an
> > email and I'll build a list to get the discussion started.
>
> Count me in - by 'build a list' do you mean a new mailing list?
>
> I've read http://wiki.openstack.org/UnifiedCLI/HumanInterfaceGuidelines
> (which looks like a great start on the topic!) and made some minor
> tweaks.  Should we discuss the FIXMEs you marked here or elsewhere?  I
> wanted to make a few suggestions before I forget - can always continue
> discussion elsewhere if appropriate:
>
>  1. Regarding "The subject names are always specified in command in
>     their singular form.  This is contrary to natural language use."
>
>       - I didn't understand the second sentence here, but shouldn't the
>         HIG should allow for scenarios where the verb can operate both on
>         individual objects and on multiple objects in batch?
>

I read that as meaning the command to list instances available to a tenant
should be "list server" not the more natural "list servers".

Can you give an example of a command that would work on multiple objects in
batch?


>
>     (Grammatical nitpick: if the verb is acting on the noun, then the
>     HIG should refer to the noun as "object" rather than "subject".)
>
>  2. I think it would be good if the HIG gave guidelines on how the
>     command should behave when run with no arguments.
>

Running a cliff-based app without any arguments enters "interactive" mode
(as of 0.4) which gives the user a new prompt and lets them run multiple
commands before exiting. This is intended to be used as an optimization for
commands to cache authentication credentials and clients and avoid logging
in for every sub-command.

Since we're using argparse for the subcommands, the default behavior if a
command is run without arguments depends on the subcommand. If the
subcommand has no required arguments, it will do whatever it is meant to
do. If it does require arguments and sees none, argparse prints an error
message about whatever is missing (and possibly suggests that the user use
--help to get instructions).


>
>  3. I think it would be good if the HIG recommended that, at least
>     when subcommands are permitted, single arguments '--help' and
>     'help' always generate identical output:
>
>       https://bugs.launchpad.net/keystone/+bug/936399
>       https://review.openstack.org/#/c/6460/


The current version of cliff eats the --help option no matter where it
appears on the command line, so to get help on a subcommand you always have
to use "help" (without the dashes).

$ openstack --help
$ openstack list server --help

both print the help for the "openstack" command, including a list of
available subcommands

$ openstack help list server

prints the help for the "list server" subcommand of "openstack"


>  4. I think it would be good if the HIG gave guidelines on how the
>     help text should be formatted - in particular that positional
>     arguments are covered by the help text (e.g. keystone-manage does
>     not currently give any info on positional arguments required
>     until you specify too few).
>

Do we need to specify this beyond saying that all subcommands must use
argparse for argument parsing (the new framework depends on it anyway, and
then they are all consistent)?


>
>  5. I think it would be good if the HIG specified what sort of help
>     text should be included alongside error messages of (say) the
>     "you didn't give the right number of arguments" variety, and
>     whether the error message should appear before or after that help
>     text.  My vote is after, because it's far easier for the human
>     eye to locate the end of a command's output than the beginning,
>     especially if the beginning has scrolled off the top of the
>     terminal.


> Thanks,
> Adam
>
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack
> More help   : https://help.launchpad.net/ListHelp
>