Open Stack

On 09/15/2014 05:33 PM, Clint Byrum wrote:
> Excerpts from Zane Bitter's message of 2014-09-15 09:31:33 -0700:
>> On 14/09/14 11:09, Clint Byrum wrote:
>>> Excerpts from Gauvain Pocentek's message of 2014-09-04 22:29:05 -0700:
>>>> Hi,
>>>>
>>>> A bit of background: I'm working on the publication of the HOT
>>>> resources reference on docs.openstack.org. This book is mostly
>>>> autogenerated from the heat source code, using the sphinx XML output. To
>>>> avoid publishing several references (one per released version, as is
>>>> done for the OpenStack config-reference), I'd like to add information
>>>> about the support status of each resource (when they appeared, when
>>>> they've been deprecated, and so on).
>>>>
>>>> So the plan is to use the SupportStatus class and its `version`
>>>> attribute (see https://review.openstack.org/#/c/116443/ ). And the
>>>> question is, what information should the version attribute hold?
>>>> Possibilities include the release code name (Icehouse, Juno), or the
>>>> release version (2014.1, 2014.2). But this wouldn't be useful for users
>>>> of clouds continuously deployed.
>>>>
>>>>   From my documenter point of view, using the code name seems the right
>>>> option, because it fits with the rest of the documentation.
>>>>
>>>> What do you think would be the best choice from the heat devs POV?
>>>
>>> What we ship in-tree is the standard library for Heat. I think Heat
>>> should not tie things to the release of OpenStack, but only to itself.
>>
>> "Standard Library" implies that everyone has it available, but in 
>> reality operators can (and will, and do) deploy any combination of 
>> resource types that they want.
>>
> 
> Mmk, I guess I was being too optimistic about how homogeneous OpenStack
> clouds might be.

(From Zane's other message)
> <snip>
> I think the first supported release is probably the right information
to add.
> <snip>

I feel like for anything with nonzero upgrade effort (and upgrading your
openstack install takes significantly more than 0 effort units) you can
never assume everyone is running the latest (or even a recent) revision.
That's why projects often host docs versions *way* back.

The SQLAlchemy project hosts docs back to 2012[1] and also has latest[2]
docs that are updated continuously. I think the way to support the most
use cases would be to have docs for each release as well as continue to
have CI update docs.

For a URL structure I could see docs.o.o/developer/heat/latest and
d.o.o/heat/<VER> where <VER> can be either a semver release (2014.2,
etc) or a release name (icehouse, havana, etc). The strategy SQLA and
other projects use is to feature a release date prominently at the top
of the page, so users can look and say "Oh, Juno isn't released yet, so
this feature won't be in my Icehouse cloud".

[1] http://docs.sqlalchemy.org/en/rel_0_6/core/index.html
[2] http://docs.sqlalchemy.org/en/latest/core/index.html


> 
>>> The idea is to simply version the standard library of resources separately
>>> even from the language. Added resources and properties would be minor
>>> bumps, deprecating or removing anything would be a major bump. Users then
>>> just need an API call that allows querying the standard library version.
>>
>> We already have API calls to actually inspect resource types. I don't 
>> think a semantic version number is helpful here, since the different 
>> existing combinations of resources types are not expressible linearly.
>>
>> There's no really good answer here, but the only real answer is making 
>> sure it's easy for people to generate the docs themselves for their 
>> actual deployment.
>>
> 
> That's an interesting idea. By any chance do we have something that
> publishes the docs directly from source tree into swift? Might make it
> easier if we could just do that as part of code pushes for those who run
> clouds from source.
> 
>>> With this scheme, we can provide a gate test that prevents breaking the
>>> rules, and automatically generate the docs still. Doing this would sync
>>> better with continuous deployers who will be running "Juno" well before
>>> there is a "2014.2".
>>
>> Maybe continuous deployers should continuously deploy their own docs? 
>> For any given cloud the only thing that matters is what it supports 
>> right now.
>>
> 
> Thats an interesting idea, but I like what the user wants is to see how
> this cloud is different than the other clouds.
> 
>>> Anyway, Heat largely exists to support portability of apps between
>>> OpenStack clouds. Many many OpenStack clouds don't run one release,
>>> and we don't require them to do so. So tying to the release is, IMO,
>>> a poor coice.
>>
>> The original question was about docs.openstack.org, and in that context 
>> I think tying it to the release version is a good choice, because 
>> that's... how OpenStack is released. Individual clouds, however, really 
>> need to deploy their own docs that document what they actually support.
>>
> 
> Yeah I hadn't thought of that before. I like the idea but I wonder how
> practical it is for CD private clouds.
> 
>> The flip side of this, of course, is that whatever we use for the 
>> version strings on docs.openstack.org will all make its way into all the 
>> other documentation that gets built, and I do understand your point in 
>> that context. But versioning the "standard library" of plugins as if it 
>> were a monolithic, always-available thing seems wrong to me.
>>
> 
> Yeah I think it is too optimistic in retrospect.
> 
>>> We do the same thing with HOT's internals, so why not also
>>> do the standard library this way?
>>
>> The current process for HOT is for every OpenStack development cycle 
>> (Juno is the first to use this) to give it a 'version' string that is 
>> the expected date of the next release (in the future), and continuous 
>> deployers who use the new one before that date are on their own (i.e. 
>> it's not considered stable). So not really comparable.
>>
> 
> I think there's a difference between a CD operator making it available,
> and saying they support it. Just like a new API version in OpenStack, it
> may be there, but they may communicate to users it is alpha until after
> it gets released upstream. I think that is the same for this, and so I
> think that using the version number is probably fine.
> 
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> 

-- 
Ryan Brown / Software Engineer, Openstack / Red Hat, Inc.