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@lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > -- Ryan Brown / Software Engineer, Openstack / Red Hat, Inc. _______________________________________________ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
