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 melwi...@gmail.com 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 19:28, Chris St. Pierre chris.a.st.pie...@gmail.com 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 melanie witt
On Mar 10, 2015, at 7:32, Chris St. Pierre chris.a.st.pie...@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)







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