Re: [openstack-dev] [python-novaclient] Better wording for secgroup-*-default-rules? help text

2015-03-10 Thread melanie witt
On Mar 10, 2015, at 19:28, Chris St. Pierre  wrote:

> Ah, look at that! In some other projects, flake8 complains about a docstring 
> whose first line doesn't end in a period, so I didn't think it'd be possible. 
> If you don't think that's excessively verbose, there'll be a patch in 
> shortly. Thanks!

Oh, right -- I wasn't thinking about that. Probably it's not a restriction in 
novaclient because documentation is generated from the docstrings.

> That's precisely the confusion -- the security group name 'default' is, of 
> course, a security group. But "the default security group," as referenced by 
> the help text for these commands, is actually a sort of meta-security-group 
> object that is only used to populate the 'default' security group in new 
> tenants. It is not, in and of itself, an actual security group. That is, 
> adding a new rule with 'nova secgroup-add-default-rules' has absolutely no 
> effect on what network traffic is allowed between guests; it only affects new 
> tenants created afterwards.

Got it. I learned a lot about the "default security group" in nova-network 
because of your email and bug. It's actually generated if it doesn't exist for 
a tenant when a server is created. If it's found, it's reused and thus won't 
pick up any default rules that had been added since it was created. And then 
you could get into particulars like deleting the 'default' group, then you 
would get all freshest default rules next time you create a server, even if 
your tenant isn't new. Really not easy to understand.

melanie (melwitt)







signature.asc
Description: Message signed with OpenPGP using GPGMail
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


Re: [openstack-dev] [python-novaclient] Better wording for secgroup-*-default-rules? help text

2015-03-10 Thread Chris St. Pierre
On Tue, Mar 10, 2015 at 4:50 PM, melanie witt  wrote:
>
> 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.
>

Ah, look at that! In some other projects, flake8 complains about a
docstring whose first line doesn't end in a period, so I didn't think it'd
be possible. If you don't think that's excessively verbose, there'll be a
patch in shortly. Thanks!

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?
>

That's precisely the confusion -- the security group name 'default' is, of
course, a security group. But "the default security group," as referenced
by the help text for these commands, is actually a sort of
meta-security-group object that is only used to populate the 'default'
security group in new tenants. It is not, in and of itself, an actual
security group. That is, adding a new rule with 'nova
secgroup-add-default-rules' has absolutely no effect on what network
traffic is allowed between guests; it only affects new tenants created
afterwards.

-- 
Chris St. Pierre
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


Re: [openstack-dev] [python-novaclient] Better wording for secgroup-*-default-rules? help text

2015-03-10 Thread melanie witt
On Mar 10, 2015, at 7:32, Chris St. Pierre  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)







signature.asc
Description: Message signed with OpenPGP using GPGMail
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev