openstack team mailing list archive

[Dolph Mathews <dolph.mathews@xxxxxxxxx>]

On Mon, Apr 30, 2012 at 1:18 PM, Doug Hellmann
<doug.hellmann@xxxxxxxxxxxxx>wrote:

>
>
> 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".
>

I really hope that "list servers" would work.


>
> 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.
>

One solution for this today is to use keystone's existing "token_get"
command, and then run subsequent commands with your specified token. So,
it's basically one request per command, instead of complete auth + request
per command.

    $ keystone token-get
    $ keystone --token=$TOKEN --endpoint=$ENDPOINT tenant-create [...]


>
> 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"
>

I find this behavior really annoying... --help should be contextual
(depending on whether a subcommand is present, and what it is).


>
>

>
>>  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)?
>

I hope not... +1 for argparse.


>
>
>>
>>  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
>>
>
>
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack
> More help   : https://help.launchpad.net/ListHelp
>
>