Open Stack

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