Open Stack

On Aug 24, 2011, at 12:02 PM, Soren Hansen wrote:

2011/8/24 Jorge Williams <jorge.williams at rackspace.com<mailto:jorge.williams at rackspace.com>>:
Let me start by saying that I have no idea why we're having this
discussion again. We talked about it at the design summit and we
agreed we'd move forward in pretty much exactly the way Vish describes
it.
I believe I attended all discussions on the compute API.   We agreed
to design the spec in a more open and agile manner -- I'm all for
that.  I don't remember ever discussing generating the spec from code.

Generating the spec from code (or docstrings living in code, rather) was
informally discussed in San Antonio in November.

I also don't remember ever discussing where the spec will live.  Not
that I really care where it lives, I just don't remember talking about
it.

This was the subject for an entire session in Santa Clara. Making code
and docuemtation live together to ensure they'd be in sync at all times.


Okay, I do remember these, but the talks focus on documenting what the implementation does.  I'm all for it, docstrings are good, but that's not what I usually think of a specification.  So  we are having a semantic disconnect here....

OpenStack was created to stop every company wanting to do offer cloud
computing from reinventing everything and have everyone work together.
What's the use of competing implementations? We'll be right back to square one.

Because whether you like it or not there are competing vendors... and each wants to add it's special sauce in order to remain competitive. Also, because companies that have existing products may find it easier to add an OpenStack compatibility layer rather then switching to our implementation -- at least in the short term.  (As long as they use our API we still win from this.) And finally, because it's hard to write an implementation that's all things to all people.  Other implementations may want to specialize in one manner or another.

I've been doing some research to try to understand the disconnect that we are having.   For example, the idea of multiple implementations and the separation of spec from implementation seems quite natural to me, but is obviously alien to others.  I've found a great blog post that illustrates the difference, and states that it seems to stem from the fact that there are cultural differences between coding languages.  Note the blog is from PJ Eby,  the author of PEP 333.  Worth a read:

http://dirtsimple.org/2004/12/java-is-not-python-either.html


Like, say,  having the
spec be generated from docstrings in the code and at the same time run
tests based on the contents of the docstrings to ensure that what the
docstrings says the API will accept and return is also what it actually
accepts.


I like this approach to testing because the docstrings aren't generated from what the code does, they are written by hand. This is a good approach for confirming that the impl meets up with the spec.  I'm not so sure that there would be enough there to document things in enough detail though to form as the basis of the spec.


-jOrGe W.

This email may include confidential information. If you received it in error, please delete it.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack/attachments/20110825/8dd924a1/attachment.html>