openstack team mailing list archive

[Adam Spiers <aspiers@xxxxxxxx>]

Dean Troyer (dtroyer@xxxxxxxxx) 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?

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

  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/

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

  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