On Thu, Aug 11, 2016 at 6:13 PM, John Dickinson <m...@not.mn> wrote: > > > On 11 Aug 2016, at 15:02, Brian Rosmaita wrote: > >> I have a question about the api-ref. Right now, for example, the new >> images v1/v2 api-refs are accurate for Mitaka. But DocImpact bugs are >> being generated as we speak for changes in master that won't be >> available to consumers until Newton is released (unless they build from >> source). If those bug fixes get merged, then the api-ref will no longer >> be accurate for Mitaka API consumers (since it's published upon update). >> >> My question is, how should we handle this? We want the api-ref to be >> accurate for users, but we also want to move quickly on updates (so that >> the updates actually get made in a timely fashion). >> >> My suggestion is that we should always have an api-ref available that >> reflects the stable releases, that is, one for each stable branch. So >> right now, for instance, the default api-ref page would display the >> api-ref for Mitaka, with links to "older" (Liberty) and "development" >> (master). But excellent as that suggestion is, it doesn't help right >> now, because the most accurate Mitaka api-ref for Glance, for instance, >> is in Glance master as part of the WADL to RST migration project. What >> I'd like to do is publish a frozen version of that somewhere as we make >> the Newton updates along with the Newton code changes. >> >> Thus I guess I have two questions: >> >> (1) How should we version (and publish multiple versions of) the api-ref >> in general? >> >> (2) How do we do it right now? >> >> thanks, >> brian >> > > I was working with the oslosphinx project to try and solve this issue in a > cross-project way for the dev docs. I think the ideas there could be useful > here. > > Basically, if you have docs built every commit (instead of every release, > like normally happens with library projects), you can set show_other_versions > to True and get a sidebar link of versions based on tags. (Yeah, I know it > wasn't working earlier, but that should be fixed now). > > So with this process, keep building docs per commit so you have the latest > available. But turn on the sidebar links for other versions, and you can have > a place for docs from the last few releases in your project. I'm not sure > that it would work well for stable branches that are updated (but really, if > you're updating stable, how "stable" is it?)
We actually publish per-release dev docs right now, though the sidebar seems broken: master: http://docs.openstack.org/developer/swift/ stable release: http://docs.openstack.org/developer/swift/mitaka/ intermediate release: http://docs.openstack.org/developer/swift/2.9.0/ // jim > > > --John > > > > >> >> __________________________________________________________________________ >> OpenStack Development Mailing List (not for usage questions) >> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > > __________________________________________________________________________ > OpenStack Development Mailing List (not for usage questions) > Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
