Open Stack

On 09/06/2016 11:42 AM, Ihar Hrachyshka wrote:
> 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?

The solution we've been using in Nova is "fix it in english". We move
deprecated stuff towards the end of the document, mark it deprecated,
and add explanatory language around the API about it.
http://developer.openstack.org/api-ref/compute/#ping-instances-os-fping-deprecated
is maybe a reasonable example.

The important thing is that if you have multiple versions of your API
reference document, no one will know if they are on the right one. If
you have one version, and explain "this has been removed, might not be
in your installation, you can find out if it's available with X Y Z".
Then all consumers have the same view of the world, will know they are
on the one true document.

When do delete is tricky. There are public clouds running Kilo right
now. So 4 cycles at least if you don't want to strand users.

	-Sean

-- 
Sean Dague
http://dague.net