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