Open Stack

One important clarification I need to make is that these aren't actually just "Tom's Tables" ;)

I've had some awesome help from Steven Deaton at Rackspace, who's been cleaning and extending my poor-quality original code and doing a ton of conceptual work.

Thanks, Steven :)


Regards,

Tom


________________________________
From: Tom Fifield [fifieldt at unimelb.edu.au]
Sent: Tuesday, 14 May 2013 11:21 AM
To: Joe Topjian; openstack-docs at lists.openstack.org
Subject: Re: [Openstack-docs] Tom's Tables

Hi Joe,

Thanks for starting the discussion. Also looping in Anne's and Lorin's comments.


  *   * Should there be the ability to override or append the description of an option in case the current description is not clear? Or should the proper fix be to patch the source file where the option is defined?

I think the only sustainable way to do this is for the source code to be the definitive place for the option text. For Grizzly we might have to fake it, but I believe that for Havana we (plus the entire developer army) need to be patching the strings in the code, before the string freeze sets in.


  *   * [ What about ] the ability to group configuration options into "config sets" such as an "HA config set requires these options" or "A Quantum agent needs these".

So, the initial manual groupings took some work, but were fairly straightforward since each has a single group (where options are in multiple groups, they have multiple entries). There is the potential to expand on this infinitely, and to some degree it will make sense. However, I believe the most important aspect of this work is sustainability, and it would be my desire that eventually the manually created group mappings are derived from code - meaning the entire process could be automated. There is functionality in oslo.config that could be used to start this work. Until that happens, however, we're free to play to see what groupings make sense :)


  *   If possible, can the script put a <!-- --> comment in the XML at the top of the file to indicate the source file?

I found this comment a little ambiguous, so I'm assuming: what is desired is for the ability to find where a particular option is defined in the code of the product from which it comes. Each table typically has multiple places in the code used to make it, so it would need to be per-option, rather than per table. Unfortunately, the short term answer here is no. When pulling in a module's config you tend to pull in those of every other module in the product that the particular module relies on, so it's not possible to split stuff out by file without some work. Personally, I just grep -R <option_name> * ;)



  *   Comments about "context" of options.

Anne made some comments about specific options in OpenStack Networking such as "host" or "server auth". I believe that the solution here is just to fix the crap text, pure and simple. So far I have lodged several bugs about missing or misleading option text and got good response from developers involved - again along the idea that we shouldn't have to do all of this ourselves.


I also believe that this configuration tables should - at a minimum - be included in a file with a paragraph at the top that has an context-providing explanation. "These are the options for the CISCO Quantum Plugin.


This plugin implementation provides the following capabilities:

    A reference implementation for a Quantum Plugin Framework (For details see: http://wiki.openstack.org/quantum-multi-switch-plugin)
     Supports multiple switches in the network
     Supports multiple models of switches concurrently
     Supports use of multiple L2 technologies
     Supports the Cisco Nexus family of switches (Verified with Nexus 3000, 5000 and 7000 series)
    If you are using a Nexus switch in your topology, you'll need the following NX-OS version and packages to enable Nexus support:
         NX-OS 5.2.1 (Delhi) Build 69 or above.
        paramiko library - SSHv2 protocol library for python
        ncclient v0.3.1 - Python library for NETCONF clients"



  *

I think this is a good idea, to point out what information is missing.

Yes, indeed - and this is I think where our work is. Instead of constantly fixing things ourselves, we should be (I have been already, yay) lodging bugs about missing/misleading text.



HTH!





Regards,


Tom
________________________________
From: Joe Topjian [joe.topjian at cybera.ca]
Sent: Tuesday, 14 May 2013 1:18 AM
To: openstack-docs at lists.openstack.org
Subject: [Openstack-docs] Tom's Tables

Hello,

I figured I'd send an email about Tom's table creation rather than commenting on each (or just one) of the patch sets that he submitted.

I think the tables are great. Even if they were published as they are right now, I think just having the ability to create accurate tables like that is a great feature.

Should there be the ability to override or append the description of an option in case the current description is not clear? Or should the proper fix be to patch the source file where the option is defined? I can see pros and cons to both. Pro being a single source of information. Con being the amount of time/effort it would take to backport a description to an older release.

The only thing I find missing from the tables is how they can be used beyond a reference point (although beyond a reference point is more of a "feature request"). Looking through Tom's github repo, I see that the groupings have to be done manually. I'm curious about what others would think about expanding on that idea. For example, the ability to group configuration options into "config sets" such as an "HA config set requires these options" or "A Quantum agent needs these".

Thanks,
Joe

--
Joe Topjian
Systems Administrator
Cybera Inc.

www.cybera.ca<http://www.cybera.ca>

Cybera is a not-for-profit organization that works to spur and support innovation, for the economic benefit of Alberta, through the use of cyberinfrastructure.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20130514/5d827c48/attachment-0001.html>