<div class="gmail_extra"><br><br><div class="gmail_quote">On Mon, Apr 30, 2012 at 3:19 PM, Dolph Mathews <span dir="ltr"><<a href="mailto:dolph.mathews@gmail.com" target="_blank">dolph.mathews@gmail.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="gmail_extra"><br><br><div class="gmail_quote"><div class="im">On Mon, Apr 30, 2012 at 1:18 PM, Doug Hellmann <span dir="ltr"><<a href="mailto:doug.hellmann@dreamhost.com" target="_blank">doug.hellmann@dreamhost.com</a>></span> wrote:<br>
</div><div class="im"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="gmail_extra"><br><br><div class="gmail_quote"><div>On Mon, Apr 30, 2012 at 12:13 PM, Adam Spiers <span dir="ltr"><<a href="mailto:aspiers@suse.com" target="_blank">aspiers@suse.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div>Dean Troyer (<a href="mailto:dtroyer@gmail.com" target="_blank">dtroyer@gmail.com</a>) wrote:<br>
> One of the first things to do is to find out who is interested in<br>
> contributing to this project.and hopefully coordinating some of the<br>
> work with the other emerging project-specific clients. Send me an<br>
> email and I'll build a list to get the discussion started.<br>
<br>
</div>Count me in - by 'build a list' do you mean a new mailing list?<br>
<br>
I've read <a href="http://wiki.openstack.org/UnifiedCLI/HumanInterfaceGuidelines" target="_blank">http://wiki.openstack.org/UnifiedCLI/HumanInterfaceGuidelines</a><br>
(which looks like a great start on the topic!) and made some minor<br>
tweaks. Should we discuss the FIXMEs you marked here or elsewhere? I<br>
wanted to make a few suggestions before I forget - can always continue<br>
discussion elsewhere if appropriate:<br>
<br>
1. Regarding "The subject names are always specified in command in<br>
their singular form. This is contrary to natural language use."<br>
<br>
- I didn't understand the second sentence here, but shouldn't the<br>
HIG should allow for scenarios where the verb can operate both on<br>
individual objects and on multiple objects in batch?<br></blockquote><div><br></div></div><div>I read that as meaning the command to list instances available to a tenant should be "list server" not the more natural "list servers".</div>
</div></div></blockquote><div><br></div></div><div>I really hope that "list servers" would work.</div></div></div></blockquote><div><br></div><div>I tend to agree, I was just explaining how I interpreted what was there.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="gmail_extra"><div class="gmail_quote"><div class="im"><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div class="gmail_extra">
<div class="gmail_quote">
<div><br></div><div>Can you give an example of a command that would work on multiple objects in batch?</div><div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
(Grammatical nitpick: if the verb is acting on the noun, then the<br>
HIG should refer to the noun as "object" rather than "subject".)<br>
<br>
2. I think it would be good if the HIG gave guidelines on how the<br>
command should behave when run with no arguments.<br></blockquote><div><br></div></div><div>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.</div>
</div></div></blockquote><div><br></div></div><div>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.</div>
<div><br></div><div> $ keystone token-get</div><div> $ keystone --token=$TOKEN --endpoint=$ENDPOINT tenant-create [...]</div></div></div></blockquote><div><br></div><div>That sounds sort of like the way ssh-agent works, and I like that as an optimization, too.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="gmail_extra"><div class="gmail_quote"><div class="im"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div class="gmail_extra"><div class="gmail_quote"><div>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).</div>
<div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
3. I think it would be good if the HIG recommended that, at least<br>
when subcommands are permitted, single arguments '--help' and<br>
'help' always generate identical output:<br>
<br>
<a href="https://bugs.launchpad.net/keystone/+bug/936399" target="_blank">https://bugs.launchpad.net/keystone/+bug/936399</a><br>
<a href="https://review.openstack.org/#/c/6460/" target="_blank">https://review.openstack.org/#/c/6460/</a></blockquote><div><br></div></div><div>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).</div>
<div><br></div><div>$ openstack --help</div><div>$ openstack list server --help</div><div><br></div><div>both print the help for the "openstack" command, including a list of available subcommands</div><div><br>
</div>
<div>$ openstack help list server</div><div><br></div><div>prints the help for the "list server" subcommand of "openstack"</div></div></div></blockquote><div><br></div></div><div>I find this behavior really annoying... --help should be contextual (depending on whether a subcommand is present, and what it is).</div>
</div></div></blockquote><div><br></div><div>That's how it worked originally. When I got the pull-request from Dean I assumed it was intended to follow some existing standard.</div><div><br></div><div>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.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="gmail_extra"><div class="gmail_quote"><div class="im"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div class="gmail_extra"><div class="gmail_quote"><div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
4. I think it would be good if the HIG gave guidelines on how the<br>
help text should be formatted - in particular that positional<br>
arguments are covered by the help text (e.g. keystone-manage does<br>
not currently give any info on positional arguments required<br>
until you specify too few).<br></blockquote><div><br></div></div><div>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)?</div>
</div></div></blockquote><div><br></div></div><div>I hope not... +1 for argparse.</div><div class="im"><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="gmail_extra">
<div class="gmail_quote">
<div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
5. I think it would be good if the HIG specified what sort of help<br>
text should be included alongside error messages of (say) the<br>
"you didn't give the right number of arguments" variety, and<br>
whether the error message should appear before or after that help<br>
text. My vote is after, because it's far easier for the human<br>
eye to locate the end of a command's output than the beginning,<br>
especially if the beginning has scrolled off the top of the<br>
terminal. </blockquote><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
Thanks,<br>
Adam<br>
<div><div><br>
_______________________________________________<br>
Mailing list: <a href="https://launchpad.net/~openstack" target="_blank">https://launchpad.net/~openstack</a><br>
Post to : <a href="mailto:openstack@lists.launchpad.net" target="_blank">openstack@lists.launchpad.net</a><br>
Unsubscribe : <a href="https://launchpad.net/~openstack" target="_blank">https://launchpad.net/~openstack</a><br>
More help : <a href="https://help.launchpad.net/ListHelp" target="_blank">https://help.launchpad.net/ListHelp</a><br>
</div></div></blockquote></div></div><br></div>
<br>_______________________________________________<br>
Mailing list: <a href="https://launchpad.net/~openstack" target="_blank">https://launchpad.net/~openstack</a><br>
Post to : <a href="mailto:openstack@lists.launchpad.net" target="_blank">openstack@lists.launchpad.net</a><br>
Unsubscribe : <a href="https://launchpad.net/~openstack" target="_blank">https://launchpad.net/~openstack</a><br>
More help : <a href="https://help.launchpad.net/ListHelp" target="_blank">https://help.launchpad.net/ListHelp</a><br>
<br></blockquote></div></div><br></div>
</blockquote></div><br></div>