<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Mon, Sep 15, 2014 at 11:31 AM, Zane Bitter <span dir="ltr"><<a href="mailto:zbitter@redhat.com" target="_blank">zbitter@redhat.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class="">On 14/09/14 11:09, Clint Byrum wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Excerpts from Gauvain Pocentek's message of 2014-09-04 22:29:05 -0700:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Hi,<br>
<br>
A bit of background: I'm working on the publication of the HOT<br>
resources reference on <a href="http://docs.openstack.org" target="_blank">docs.openstack.org</a>. This book is mostly<br>
autogenerated from the heat source code, using the sphinx XML output. To<br>
avoid publishing several references (one per released version, as is<br>
done for the OpenStack config-reference), I'd like to add information<br>
about the support status of each resource (when they appeared, when<br>
they've been deprecated, and so on).<br>
<br>
So the plan is to use the SupportStatus class and its `version`<br>
attribute (see <a href="https://review.openstack.org/#/c/116443/" target="_blank">https://review.openstack.org/#<u></u>/c/116443/</a> ). And the<br>
question is, what information should the version attribute hold?<br>
Possibilities include the release code name (Icehouse, Juno), or the<br>
release version (2014.1, 2014.2). But this wouldn't be useful for users<br>
of clouds continuously deployed.<br>
<br>
  From my documenter point of view, using the code name seems the right<br>
option, because it fits with the rest of the documentation.<br>
<br>
What do you think would be the best choice from the heat devs POV?<br>
</blockquote>
<br>
What we ship in-tree is the standard library for Heat. I think Heat<br>
should not tie things to the release of OpenStack, but only to itself.<br>
</blockquote>
<br></span>
"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.<span class=""><br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
The idea is to simply version the standard library of resources separately<br>
even from the language. Added resources and properties would be minor<br>
bumps, deprecating or removing anything would be a major bump. Users then<br>
just need an API call that allows querying the standard library version.<br>
</blockquote>
<br></span>
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.<br>
<br>
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.</blockquote><div><br></div><div>In my observations there could be a few private clouds generating user docs based on upstream, but there have to be many, many more private clouds than public, so it's better if <a href="http://docs.openstack.org">docs.openstack.org</a> can take on the work here for sharing the docs burden for users specifically. </div><div><br></div><div>Because we've had multiple inputs asking for heat docs that are released, I'd like to see Gauvain's naming/numbering go into upstream.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class=""><br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
With this scheme, we can provide a gate test that prevents breaking the<br>
rules, and automatically generate the docs still. Doing this would sync<br>
better with continuous deployers who will be running "Juno" well before<br>
there is a "2014.2".<br>
</blockquote>
<br></span>
Maybe continuous deployers should continuously deploy their own docs? For any given cloud the only thing that matters is what it supports right now.<span class=""><br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Anyway, Heat largely exists to support portability of apps between<br>
OpenStack clouds. Many many OpenStack clouds don't run one release,<br>
and we don't require them to do so. So tying to the release is, IMO,<br>
a poor coice.<br>
</blockquote>
<br></span>
The original question was about <a href="http://docs.openstack.org" target="_blank">docs.openstack.org</a>, 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.<br></blockquote><div><br></div><div>We only really release two types of documents - the Install Guides and the Configuration Reference. We have purposely continuously released user guide info and the HOT templates fall under that category. So this document will be updated any time someone gets a patch merged. Because of this CI for docs, labels are critical to aid understanding.</div><div><br></div><div>Anne</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
The flip side of this, of course, is that whatever we use for the version strings on <a href="http://docs.openstack.org" target="_blank">docs.openstack.org</a> 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.<span class=""><br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
We do the same thing with HOT's internals, so why not also<br>
do the standard library this way?<br>
</blockquote>
<br></span>
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.<br>
<br>
cheers,<br>
Zane.<div class="HOEnZb"><div class="h5"><br>
<br>
______________________________<u></u>_________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org" target="_blank">OpenStack-dev@lists.openstack.<u></u>org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/<u></u>cgi-bin/mailman/listinfo/<u></u>openstack-dev</a><br>
</div></div></blockquote></div><br></div></div>