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