Open Stack

Jeremy Stanley <fungi at yuggoth.org> wrote:

> 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).

The particular case under discussion is that in Newton, Neutron removed  
LBaaS v1 API (it was deprecated for quite some time). Users are able to  
detect the presence (or absence) of the API as before, by checking if  
corresponding API extension alias is in the list of active API extensions  
as returned by /extensions neutron API. Now, in Newton, the extension is  
*always* disabled, because there is no way to enable it (the code is gone).  
In Mitaka and Liberty though, it depends on whether the lbaasv1 service  
plugin is enabled in particular setup.

There are two related but separate questions here:
- is there time when we can drop API from api-ref when it’s removed in code?
- if so, when is it: right when the API is dropped, or when all branches  
supporting it are gone? or should we document the non-existing API  
indefinitely?

Ihar