On Mon, Apr 30, 2012 at 3:19 PM, Dolph Mathews <dolph.math...@gmail.com>wrote:
> > > On Mon, Apr 30, 2012 at 1:18 PM, Doug Hellmann < > doug.hellm...@dreamhost.com> wrote: > >> >> >> On Mon, Apr 30, 2012 at 12:13 PM, Adam Spiers <aspi...@suse.com> wrote: >> >>> Dean Troyer (dtro...@gmail.com) 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. > I tend to agree, I was just explaining how I interpreted what was there. > > >> >> 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 [...] > That sounds sort of like the way ssh-agent works, and I like that as an optimization, too. > 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). > That's how it worked originally. When I got the pull-request from Dean I assumed it was intended to follow some existing standard. >From an implementation perspective, it was challenging to use two levels of argparse parsers to have the --help option applied separately, so I had the main app using optparse configured to stop at the first positional argument (value without a "-" at the front). That was a little ugly, since it depended on a deprecated module. I was not able to find a way to do exactly the same thing in argparse without adding some of my own logic on top. > 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@lists.launchpad.net >>> Unsubscribe : https://launchpad.net/~openstack >>> More help : https://help.launchpad.net/ListHelp >>> >> >> >> _______________________________________________ >> Mailing list: https://launchpad.net/~openstack >> Post to : openstack@lists.launchpad.net >> Unsubscribe : https://launchpad.net/~openstack >> More help : https://help.launchpad.net/ListHelp >> >> >
_______________________________________________ Mailing list: https://launchpad.net/~openstack Post to : openstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack More help : https://help.launchpad.net/ListHelp
