Open Stack

On Mar 10, 2015, at 7:32, Chris St. Pierre <chris.a.st.pierre at gmail.com> wrote:

> I've just filed a bug on the confusing wording of help text for the secgroup-{add,delete,list}-default-rules? commands: https://bugs.launchpad.net/python-novaclient/+bug/1430354
> 
> As I note in the bug, though, I'm not sure the best way to fix this. In an unconstrained world, I'd like to see something like:
> 
>     secgroup-add-default-rule   Add a rule to the set of rules that will be added to the 'default' security group in a newly-created tenant.
> 
> But that's obviously excessively verbose. And the help strings are pulled from the docstrings of the functions that implement the commands, so we're limited to what can fit in a one-line docstring. (We could add another source of help documentation -- e.g., `desc = getattr(callback, "help", callback.__doc__) or ''` on novaclient/shell.py line 531 -- but that seems like it should be a last resort.)
> 
> How can we clean up the wording to make it clear that "the default security group" is, in fact, not "the 'default' security group" or "the security group which is default," but rather another beast entirely which isn't even actually a security group?
> 
> Naming: still the hardest problem in computer science. :(

I don't think your suggestion for the help text is excessively verbose. There are already longer help texts for some commands than that, and I think it's important to accurately explain what commands do. You can use a multiline docstring to have a longer help text.

Why do you say "the default security group" isn't actually a security group? The fact that it's per-tenant and therefore not necessarily consistent?

melanie (melwitt)





-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 496 bytes
Desc: Message signed with OpenPGP using GPGMail
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20150310/3ac8b2e8/attachment.pgp>