openstack team mailing list archive
-
openstack team
-
Mailing list archive
-
Message #11024
Re: OpenStack Client Followup
Dean Troyer (dtroyer@xxxxxxxxx) wrote:
> On Tue, May 1, 2012 at 2:11 PM, Adam Spiers <aspiers@xxxxxxxx> 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?
Follow ups
References