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

[Sean Dague]

On 09/06/2016 11:42 AM, Ihar Hrachyshka wrote:
> Jeremy Stanley  wrote:
> 
>> On 2016-09-06 15:36:42 +0200 (+0200), Andreas Jaeger wrote:
>>> On 2016-09-06 15:30, Ihar Hrachyshka wrote:
 Andreas Jaeger  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

__
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

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

[Jeremy Stanley]

On 2016-09-06 17:42:03 +0200 (+0200), Ihar Hrachyshka wrote:
[...]
> 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?

Agreed, this is where opinions are going to start coming into play
because there's a trade-off in trying to maintain documentation for
dead-end features indefinitely. Ideally you'd keep it documented
until such time as you feel there's not enough people likely to
still be relying on the documentation for that feature in the wild
(once major service providers and distributions are no longer
supporting it). That could be a long time though, and there are no
easy answers... it's a matter of your documentation authors weighing
cost and benefit to pick an appropriate time for the project and its
downstream consumers.

Though hopefully once you do drop it, there's not much burden to
indefinitely maintaining a note in the documentation acknowledging
that it used to exist (perhaps mentioning the location in revision
control from where the old documentation source could be exhumed)?
-- 
Jeremy Stanley

__
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

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

[Anne Gentle]

On Tue, Sep 6, 2016 at 10:44 AM, Ihar Hrachyshka 
wrote:

> Alexander  wrote:
>
> FYI,
>>
>> A similar discussion was held for an api-ref change in Glance:
>> https://review.openstack.org/#/c/356693/
>>
>
> Thanks for the link, it led me to this discussion:
> http://lists.openstack.org/pipermail/openstack-dev/2016-August/101501.html
>
> From the looks of it, seems like the result of the discussion is glance
> folks tagging new API with micro-versions. In Neutron, we don’t have
> micro-versioning, though we have /extensions API that would allow to detect
> if a particular API is available. In particular case of dropping lbaasv1,
> it would mean we keep reference for the API for some time while stating
> it’s never available in Newton+?


Glance does not have microversioning either.

Yes, you need to keep the API reference for quite a long time (years). In
one page, note that the API version for the service is not available for
deployment in Newton+.

Anne


>
>
> Ihar
>



-- 
Anne Gentle
www.justwriteclick.com
__
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

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

[Ihar Hrachyshka]

Alexander  wrote:


FYI,

A similar discussion was held for an api-ref change in Glance:
https://review.openstack.org/#/c/356693/


Thanks for the link, it led me to this discussion:
http://lists.openstack.org/pipermail/openstack-dev/2016-August/101501.html

From the looks of it, seems like the result of the discussion is glance  
folks tagging new API with micro-versions. In Neutron, we don’t have  
micro-versioning, though we have /extensions API that would allow to detect  
if a particular API is available. In particular case of dropping lbaasv1,  
it would mean we keep reference for the API for some time while stating  
it’s never available in Newton+?


Ihar

__
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

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

[Ihar Hrachyshka]

Jeremy Stanley  wrote:


On 2016-09-06 15:36:42 +0200 (+0200), Andreas Jaeger wrote:

On 2016-09-06 15:30, Ihar Hrachyshka wrote:

Andreas Jaeger  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

__
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

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

[Jeremy Stanley]

On 2016-09-06 15:36:42 +0200 (+0200), Andreas Jaeger wrote:
> On 2016-09-06 15:30, Ihar Hrachyshka wrote:
> > Andreas Jaeger  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

__
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

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

[Bashmakov, Alexander]

FYI,

A similar discussion was held for an api-ref change in Glance:
https://review.openstack.org/#/c/356693/

On Sep 6, 2016, at 6:39 AM, Andreas Jaeger 
> wrote:

On 2016-09-06 15:30, Ihar Hrachyshka wrote:
Andreas Jaeger > 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,

Andreas
--
Andreas Jaeger aj@{suse.com,opensuse.org} 
Twitter: jaegerandi
 SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
  GF: Felix Imendörffer, Jane Smithard, Graham Norton,
  HRB 21284 (AG Nürnberg)
   GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126


__
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

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

[Andreas Jaeger]

On 2016-09-06 15:30, Ihar Hrachyshka wrote:
> Andreas Jaeger  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,

Andreas
-- 
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
  SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Felix Imendörffer, Jane Smithard, Graham Norton,
   HRB 21284 (AG Nürnberg)
GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126


__
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

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

[Ihar Hrachyshka]

Andreas Jaeger  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.


Ihar

__
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

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

[Andreas Jaeger]

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,

Andreas
-- 
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
  SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Felix Imendörffer, Jane Smithard, Graham Norton,
   HRB 21284 (AG Nürnberg)
GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126


__
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

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

[John Davidge]

On 9/6/16, 2:02 PM, "Ihar Hrachyshka"  wrote:

>Akihiro Motoki  wrote:
>
>> What releases should we support in API references?
>> There are several options.
>>
>> 1. The latest stable release + master
>> 2. All supported stable releases + master
>> 3. more older releases too?
>>
>> Option 2 sounds reasonable to me.
>>
>> This question is raised in the neutron api-ref patch [1].
>> This patch drops the API reference of LBaaS v1 which was dropped in
>> Newton release.
>> At least Newton is not released yet, so I think it is better to keep
>> it until Newton is released.
>>
>> I would like to get a community consensus before moving this patch
>>forward.
>>
>> Thanks,
>> Akihiro
>
>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.
>
>The only reason why keeping all stable branches described in master would
>
>be ease of maintenance, because you don¹t need to backport any api-ref
>related fixes to previous branches.
>
>So, I would not vote for any of 3 options suggested. Instead, I would
>keep
>master api-ref documenting just the latest (master) neutron API, and keep
>
>stable releases documented in corresponding branches whenever they differ.
>
>Of course it will require to solve an issue of publishing api-ref for
>each
>of supported branches instead of just master.
>
>Ihar

I¹m inclined to agree with Ihar on this. Now that the api ref lives in
neutron-lib I think it makes sense for it to track master. If it lived
elsewhere and wasn¹t so closely coupled with release branches then option
2 would be best, but as Ihar says, the ref for older releases can belong
in the relevant branch.

John



Rackspace Limited is a company registered in England & Wales (company 
registered number 03897010) whose registered office is at 5 Millington Road, 
Hyde Park Hayes, Middlesex UB3 4AZ. Rackspace Limited privacy policy can be 
viewed at www.rackspace.co.uk/legal/privacy-policy - This e-mail message may 
contain confidential or privileged information intended for the recipient. Any 
dissemination, distribution or copying of the enclosed material is prohibited. 
If you receive this transmission in error, please notify us immediately by 
e-mail at ab...@rackspace.com and delete the original message. Your cooperation 
is appreciated.

__
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

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

[Akihiro Motoki]

2016-09-06 22:02 GMT+09:00 Ihar Hrachyshka :
> Akihiro Motoki  wrote:
>
>> What releases should we support in API references?
>> There are several options.
>>
>> 1. The latest stable release + master
>> 2. All supported stable releases + master
>> 3. more older releases too?
>>
>> Option 2 sounds reasonable to me.
>>
>> This question is raised in the neutron api-ref patch [1].
>> This patch drops the API reference of LBaaS v1 which was dropped in
>> Newton release.
>> At least Newton is not released yet, so I think it is better to keep
>> it until Newton is released.
>>
>> I would like to get a community consensus before moving this patch
>> forward.
>>
>> Thanks,
>> Akihiro
>
>
> 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.
>
> The only reason why keeping all stable branches described in master would be
> ease of maintenance, because you don’t need to backport any api-ref related
> fixes to previous branches.
>
> So, I would not vote for any of 3 options suggested. Instead, I would keep
> master api-ref documenting just the latest (master) neutron API, and keep
> stable releases documented in corresponding branches whenever they differ.
>
> Of course it will require to solve an issue of publishing api-ref for each
> of supported branches instead of just master.
>
> Ihar

Good point.

As you mentioned, the current way of publishing API references is from
the master branch.
So at the moment we need to provide API references for stable releases
in the master branch.

I honestly would like to align the way of publishing Networking API
reference with of other projects.
I'd wait input from the docs team leading this effort.

Thanks,
Akihiro

>
>
> __
> 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

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

[Ihar Hrachyshka]

Akihiro Motoki  wrote:


What releases should we support in API references?
There are several options.

1. The latest stable release + master
2. All supported stable releases + master
3. more older releases too?

Option 2 sounds reasonable to me.

This question is raised in the neutron api-ref patch [1].
This patch drops the API reference of LBaaS v1 which was dropped in
Newton release.
At least Newton is not released yet, so I think it is better to keep
it until Newton is released.

I would like to get a community consensus before moving this patch forward.

Thanks,
Akihiro


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.


The only reason why keeping all stable branches described in master would  
be ease of maintenance, because you don’t need to backport any api-ref  
related fixes to previous branches.


So, I would not vote for any of 3 options suggested. Instead, I would keep  
master api-ref documenting just the latest (master) neutron API, and keep  
stable releases documented in corresponding branches whenever they differ.


Of course it will require to solve an issue of publishing api-ref for each  
of supported branches instead of just master.


Ihar

__
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

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

[Miguel Angel Ajo Pelayo]

Option 2 sounds reasonable to me too. :)

On Tue, Sep 6, 2016 at 2:39 PM, Akihiro Motoki  wrote:
> What releases should we support in API references?
> There are several options.
>
> 1. The latest stable release + master
> 2. All supported stable releases + master
> 3. more older releases too?
>
> Option 2 sounds reasonable to me.
>
> This question is raised in the neutron api-ref patch [1].
> This patch drops the API reference of LBaaS v1 which was dropped in
> Newton release.
> At least Newton is not released yet, so I think it is better to keep
> it until Newton is released.
>
> I would like to get a community consensus before moving this patch forward.
>
> Thanks,
> Akihiro
>
> [1] https://review.openstack.org/#/c/362838/
>
> __
> 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-dev] [api][doc][neutron] what releases should API reference support?

[Akihiro Motoki]

What releases should we support in API references?
There are several options.

1. The latest stable release + master
2. All supported stable releases + master
3. more older releases too?

Option 2 sounds reasonable to me.

This question is raised in the neutron api-ref patch [1].
This patch drops the API reference of LBaaS v1 which was dropped in
Newton release.
At least Newton is not released yet, so I think it is better to keep
it until Newton is released.

I would like to get a community consensus before moving this patch forward.

Thanks,
Akihiro

[1] https://review.openstack.org/#/c/362838/

__
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