Re: [openstack-dev] [all] versioning the api-ref?
On Fri, Aug 26, 2016 at 7:46 AM, Bashmakov, Alexander < alexander.bashma...@intel.com> wrote: > Any more feedback on this? > Hi, I've added a comment on the review. For now, inline text descriptions are best for the context of what you're adding in that particular place. Anne > > > On Aug 18, 2016, at 10:30 AM, Bashmakov, Alexander < > alexander.bashma...@intel.com> wrote: > > > > Concrete example of an api-ref difference between Mitaka and Newton: > > https://review.openstack.org/#/c/356693/1/api-ref/source/v2/ > images-parameters.yaml > > > > -Original Message- > > From: Sean Dague [mailto:s...@dague.net] > > Sent: Thursday, August 18, 2016 10:20 AM > > To: Nikhil Komawar ; OpenStack Development > Mailing List (not for usage questions) > > Subject: Re: [openstack-dev] [all] versioning the api-ref? > > > >> On 08/18/2016 11:57 AM, Nikhil Komawar wrote: > >> I guess the intent was to indicate the need for indicating the micro > >> or in case of Glance minor version bump when required. > >> > >> The API isn't drastically different, there are new and old elements as > >> shown in the Nova api ref linked. > > > > Right, so the point is that it should all be describable in a single > document. It's like the fact that when you go to python API docs you get > things like - https://docs.python.org/2/library/wsgiref.html > > > > "New in version 2.5." > > > > Perhaps if there is a concrete example of the expected differences > between what would be in the mitaka tree vs. newton tree was can figure out > an appropriate way to express that in api-ref. > > > >-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 > > > > > __ > > 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 > -- 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] [all] versioning the api-ref?
Any more feedback on this? > On Aug 18, 2016, at 10:30 AM, Bashmakov, Alexander > wrote: > > Concrete example of an api-ref difference between Mitaka and Newton: > https://review.openstack.org/#/c/356693/1/api-ref/source/v2/images-parameters.yaml > > -Original Message- > From: Sean Dague [mailto:s...@dague.net] > Sent: Thursday, August 18, 2016 10:20 AM > To: Nikhil Komawar ; OpenStack Development Mailing > List (not for usage questions) > Subject: Re: [openstack-dev] [all] versioning the api-ref? > >> On 08/18/2016 11:57 AM, Nikhil Komawar wrote: >> I guess the intent was to indicate the need for indicating the micro >> or in case of Glance minor version bump when required. >> >> The API isn't drastically different, there are new and old elements as >> shown in the Nova api ref linked. > > Right, so the point is that it should all be describable in a single > document. It's like the fact that when you go to python API docs you get > things like - https://docs.python.org/2/library/wsgiref.html > > "New in version 2.5." > > Perhaps if there is a concrete example of the expected differences between > what would be in the mitaka tree vs. newton tree was can figure out an > appropriate way to express that in api-ref. > >-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 > > __ > 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] [all] versioning the api-ref?
Concrete example of an api-ref difference between Mitaka and Newton: https://review.openstack.org/#/c/356693/1/api-ref/source/v2/images-parameters.yaml -Original Message- From: Sean Dague [mailto:s...@dague.net] Sent: Thursday, August 18, 2016 10:20 AM To: Nikhil Komawar ; OpenStack Development Mailing List (not for usage questions) Subject: Re: [openstack-dev] [all] versioning the api-ref? On 08/18/2016 11:57 AM, Nikhil Komawar wrote: > I guess the intent was to indicate the need for indicating the micro > or in case of Glance minor version bump when required. > > The API isn't drastically different, there are new and old elements as > shown in the Nova api ref linked. Right, so the point is that it should all be describable in a single document. It's like the fact that when you go to python API docs you get things like - https://docs.python.org/2/library/wsgiref.html "New in version 2.5." Perhaps if there is a concrete example of the expected differences between what would be in the mitaka tree vs. newton tree was can figure out an appropriate way to express that in api-ref. -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 __ 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] [all] versioning the api-ref?
On 08/18/2016 11:57 AM, Nikhil Komawar wrote: > I guess the intent was to indicate the need for indicating the micro or > in case of Glance minor version bump when required. > > The API isn't drastically different, there are new and old elements as > shown in the Nova api ref linked. Right, so the point is that it should all be describable in a single document. It's like the fact that when you go to python API docs you get things like - https://docs.python.org/2/library/wsgiref.html "New in version 2.5." Perhaps if there is a concrete example of the expected differences between what would be in the mitaka tree vs. newton tree was can figure out an appropriate way to express that in api-ref. -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] [all] versioning the api-ref?
I guess the intent was to indicate the need for indicating the micro or in case of Glance minor version bump when required. The API isn't drastically different, there are new and old elements as shown in the Nova api ref linked. On 8/12/16 5:49 AM, Sean Dague wrote: > On 08/11/2016 06:02 PM, Brian Rosmaita wrote: >> 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). > I'm confused about this statement. > > Are you saying that the Glance v2 API in Mitaka and Newton are different > in some user visible ways? But both are called the v2 API? How does an > end user know which to use? > > The assumption with the api-ref work is that the API document should be > timeless (branchless), and hence why building from master is always > appropriate. That information works for all time. > > We do support microversion markup in the document, you can see some of > that in action here in the Nova API Ref - > http://developer.openstack.org/api-ref/compute/?expanded=list-servers-detail > > > -Sean > -- Thanks, Nikhil __ 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] [all] versioning the api-ref?
On 08/12/2016 01:43 PM, Jim Rollenhagen wrote:
> On Thu, Aug 11, 2016 at 6:13 PM, John Dickinson wrote:
>>
>>
>> On 11 Aug 2016, at 15:02, Brian Rosmaita wrote:
>>
>>> 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
>>>
>>
>> I was working with the oslosphinx project to try and solve this issue in a
>> cross-project way for the dev docs. I think the ideas there could be useful
>> here.
>>
>> Basically, if you have docs built every commit (instead of every release,
>> like normally happens with library projects), you can set
>> show_other_versions to True and get a sidebar link of versions based on
>> tags. (Yeah, I know it wasn't working earlier, but that should be fixed now).
>>
>> So with this process, keep building docs per commit so you have the latest
>> available. But turn on the sidebar links for other versions, and you can
>> have a place for docs from the last few releases in your project. I'm not
>> sure that it would work well for stable branches that are updated (but
>> really, if you're updating stable, how "stable" is it?)
>
> We actually publish per-release dev docs right now, though the sidebar
> seems broken:
>
> master: http://docs.openstack.org/developer/swift/
> stable release: http://docs.openstack.org/developer/swift/mitaka/
> intermediate release: http://docs.openstack.org/developer/swift/2.9.0/
The latest oslosphinx theme should fix these.
Note also that you need to set a variable in conf.py to turn on the
sidebar - it was turned on by default for some time (and there was no
variable to turn it off) and now there's there's a variable and default
is off,
Andreas
--
Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: 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] [all] versioning the api-ref?
On Thu, Aug 11, 2016 at 6:13 PM, John Dickinson wrote: > > > On 11 Aug 2016, at 15:02, Brian Rosmaita wrote: > >> 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 >> > > I was working with the oslosphinx project to try and solve this issue in a > cross-project way for the dev docs. I think the ideas there could be useful > here. > > Basically, if you have docs built every commit (instead of every release, > like normally happens with library projects), you can set show_other_versions > to True and get a sidebar link of versions based on tags. (Yeah, I know it > wasn't working earlier, but that should be fixed now). > > So with this process, keep building docs per commit so you have the latest > available. But turn on the sidebar links for other versions, and you can have > a place for docs from the last few releases in your project. I'm not sure > that it would work well for stable branches that are updated (but really, if > you're updating stable, how "stable" is it?) We actually publish per-release dev docs right now, though the sidebar seems broken: master: http://docs.openstack.org/developer/swift/ stable release: http://docs.openstack.org/developer/swift/mitaka/ intermediate release: http://docs.openstack.org/developer/swift/2.9.0/ // jim > > > --John > > > > >> >> __ >> 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 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] [all] versioning the api-ref?
On 08/11/2016 06:02 PM, Brian Rosmaita wrote: > 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). I'm confused about this statement. Are you saying that the Glance v2 API in Mitaka and Newton are different in some user visible ways? But both are called the v2 API? How does an end user know which to use? The assumption with the api-ref work is that the API document should be timeless (branchless), and hence why building from master is always appropriate. That information works for all time. We do support microversion markup in the document, you can see some of that in action here in the Nova API Ref - http://developer.openstack.org/api-ref/compute/?expanded=list-servers-detail -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] [all] versioning the api-ref?
On 11 Aug 2016, at 15:02, Brian Rosmaita wrote: > 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 > I was working with the oslosphinx project to try and solve this issue in a cross-project way for the dev docs. I think the ideas there could be useful here. Basically, if you have docs built every commit (instead of every release, like normally happens with library projects), you can set show_other_versions to True and get a sidebar link of versions based on tags. (Yeah, I know it wasn't working earlier, but that should be fixed now). So with this process, keep building docs per commit so you have the latest available. But turn on the sidebar links for other versions, and you can have a place for docs from the last few releases in your project. I'm not sure that it would work well for stable branches that are updated (but really, if you're updating stable, how "stable" is it?) --John > > __ > 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 signature.asc Description: OpenPGP digital signature __ 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] [all] versioning the api-ref?
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 __ 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
