Re: [openstack-dev] [python-novaclient] Better wording for secgroup-*-default-rules? help text
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
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
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
