[openstack-dev] [api][doc][neutron] what releases should API reference support?

Jeremy Stanley fungi at yuggoth.org
Tue Sep 6 15:30:28 UTC 2016


On 2016-09-06 15:36:42 +0200 (+0200), Andreas Jaeger wrote:
> On 2016-09-06 15:30, Ihar Hrachyshka wrote:
> > Andreas Jaeger <aj at suse.com> wrote:
> > 
> >> On 2016-09-06 15:02, Ihar Hrachyshka wrote:
> >>> [...]
> >>> Since neutron-lib is branched on stable/* boundary, I feel that it would
> >>> be fine to keep one-to-one relationship between neutron and neutron-lib
> >>> api-ref branches.
> >>
> >> We only publish the api-ref documents from master,
> > 
> > Is it a hard requirement from infra, or just the current state of
> > affairs? If the latter, we could revisit the approach. If the former, of
> > course we will accommodate.
> 
> It's the current state of affair - and how api-ref was designed AFAIK:
> To have one tree,

The argument for this stems from the fact that it's documenting an
API, not the software providing that API. While Neutron has releases
and stable branches, your API _doesn't_ (I hope!).

If I, as an end user/application author want to use your API, it's
entirely unlikely I'll even know what version of Neutron any random
provider is running. Likewise, my application/library need not
figure out what release of Neutron is in use to be able to interact
with its API, it should only need to know the reported API version.
The most complete picture of the Neutron API will, in theory, be
reflected in the API documentation in the master branch (and for
given objects/methods/parameters should mention the earliest _API_
version where they appear).
-- 
Jeremy Stanley



More information about the OpenStack-dev mailing list