Dean Troyer (dtro...@gmail.com) wrote: > On Tue, May 1, 2012 at 2:11 PM, Adam Spiers <aspi...@suse.com> wrote: > > As of my recent patch, --help is contextual in nova: > > I hadn't seen that yet... > > > and I have started work on some of the other commands too, so it would > > be helpful if we could reach a consensus on this soon ... although > > please let me know if I am wasting my time working on other commands > > due to any imminent rewrites using python-openstack! > > The continued existence of the project-specific commands is really up > to the projects themselves. I think it would be great to converge > them on things like this, but trying to get them all to work the same > is what led us to openstackclient due to backward compatibility and > all. My guess would be that the existing client binaries would live > through the 'G' release even if we decided to deprecate them now.
OK, thanks for the info. So what's the goal for this project - to enter the incubation program? to become part of openstack-common? Should it be added to http://wiki.openstack.org/Projects ? > > I agree with Dolph - there is a precedent from other well-known > > programs (git, hg, svn are the first ones I can think of) for --help > > to behave differently depending on whether or not it was preceded by a > > subcommand. So my vote is that we should definitely aim to adhere to > > this pattern. > > How about detailing it in the HIG and once we get a command or two > implemented with argument parsing we give it a shot? I took a stab at this, but it's beginning to confirm the doubts which I wrote about in https://lists.launchpad.net/openstack/msg10956.html regarding the decision to have the verb preceding the noun: openstack create --help openstack help create would require grouping of help for all the creation actions together which doesn't make much sense to me. These both seem to make more sense: openstack endpoint --help openstack help endpoint but would lead to overly long output unless they invoked man(1) on a corresponding manual page all about endpoint management, similar to how say, 'git remote --help' invokes the git-remote(1) man page which covers management of git remotes. The other option is to support a more fine-grained approach to help: openstack create endpoint --help openstack help create endpoint and then make the help action require both, e.g. $ openstack help create Usage: openstack help create OBJECT-TYPE Which type of object do you want help creating? Available identity types: catalog ec2-credentials endpoint role service tenant user user-password user-role Available compute types: absolute-limits actions aggregate bash-completion cloudpipe console-log credentials diagnostics dns dns-domain endpoints fixed-ip flavor floating-ip floating-ip-pool host image keypair meta(data) quota quota-class rate-limits resource root-password secgroup secgroup-group secgroup-rule usage vnc-console volume volume-snapshot volume-type x509-cert x509-root-cert [...] and ditto for 'openstack create --help'. (Of course, this is just a mockup and incorrectly lists some types which you would never create.) Here are the classes of use cases I can think of: 1. User has never/rarely used the (openstack) command before and needs to know overall structure of possible arguments and/or see a brief summary of common "get me started" arguments. Suggested implementation: openstack --help 2. User has used the (openstack) command before but needs to check global options. Suggested implementation: openstack --help 3. User wants to e.g. create something but isn't sure of the exact name of the type of the object to be created. Suggested implementation: openstack help create openstack create --help 4. User wants to perform one or more actions on a particular type of object e.g. volume, but isn't sure which actions are available. Suggested implementation: ???? 5. User knows both the action and object type but needs to check details of options / extra positional arguments. Suggested implementation: openstack create endpoint --help openstack help create endpoint Thoughts? _______________________________________________ Mailing list: https://launchpad.net/~openstack Post to : openstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack More help : https://help.launchpad.net/ListHelp
