Open Stack

Akihiro Motoki <amotoki at gmail.com> wrote:
> this mail focuses on neutron-specific topics. I dropped cinder and ironic tags.
> 
> 2016-08-11 23:52 GMT+09:00 Anne Gentle <annegentle at justwriteclick.com>:
>>
>>
>> On Wed, Aug 10, 2016 at 2:49 PM, Anne Gentle <annegentle at justwriteclick.com>
>> wrote:
>>>
>>> Hi all,
>>> I wanted to report on status and answer any questions you all have about
>>> the API reference and guide publishing process.
>>>
>>> The expectation is that we provide all OpenStack API information on
>>> developer.openstack.org. In order to meet that goal, it's simplest for now
>>> to have all projects use the RST+YAML+openstackdocstheme+os-api-ref
>>> extension tooling so that users see available OpenStack APIs in a sidebar
>>> navigation drop-down list.
>>>
>>> --Migration--
>>> The current status for migration is that all WADL content is migrated
>>> except for trove. There is a patch in progress and I'm in contact with the
>>> team to assist in any way. https://review.openstack.org/#/c/316381/
>>>
>>> --Theme, extension, release requirements--
>>> The current status for the theme, navigation, and Sphinx extension tooling
>>> is contained in the latest post from Graham proposing a solution for the
>>> release number switchover and offers to help teams as needed:
>>> http://lists.openstack.org/pipermail/openstack-dev/2016-August/101112.html I
>>> hope to meet the requirements deadline to get those changes landed.
>>> Requirements freeze is Aug 29.
>>>
>>> --Project coverage--
>>> The current status for project coverage is that these projects are now
>>> using the RST+YAML in-tree workflow and tools and publishing to
>>> http://developer.openstack.org/api-ref/<servicename> so they will be
>>> included in the upcoming API navigation sidebar intended to span all
>>> OpenStack APIs:
>>>
>>> designate http://developer.openstack.org/api-ref/dns/
>>> glance http://developer.openstack.org/api-ref/image/
>>> heat http://developer.openstack.org/api-ref/orchestration/
>>> ironic http://developer.openstack.org/api-ref/baremetal/
>>> keystone http://developer.openstack.org/api-ref/identity/
>>> manila http://developer.openstack.org/api-ref/shared-file-systems/
>>> neutron-lib http://developer.openstack.org/api-ref/networking/
>>> nova http://developer.openstack.org/api-ref/compute/
>>> sahara http://developer.openstack.org/api-ref/data-processing/
>>> senlin http://developer.openstack.org/api-ref/clustering/
>>> swift http://developer.openstack.org/api-ref/object-storage/
>>> zaqar http://developer.openstack.org/api-ref/messaging/
>>>
>>> These projects are using the in-tree workflow and common tools, but do not
>>> have a publish job in project-config in the jenkins/jobs/projects.yaml file.
>>>
>>> ceilometer
>>
>>
>> Sorry, in reviewing further today I found another project that does not have
>> a publish job but has in-tree source files:
>>
>> cinder
>>
>> Team cinder: can you let me know where you are in your publishing comfort
>> level? Please add an api-ref-jobs: line with a target of block-storage to
>> jenkins/jobs/projects.yaml in the project-config repo to ensure publishing
>> is correct.
>>
>> Another issue is the name of the target directory for the final URL. Team
>> ironic can I change your api-ref-jobs: line to bare-metal instead of
>> baremetal? It'll be better for search engines and for alignment with the
>> other projects URLs: https://review.openstack.org/354135
>>
>> I've also uncovered a problem where a neutron project's API does not have an
>> official service name, and am working on a solution but need help from the
>> neutron team: https://review.openstack.org/#/c/351407
> 
> I followed the discussion in https://review.openstack.org/#/c/351407
> and my understanding of the conclusion is to add API reference source
> of neutron stadium projects
> to neutron-lib and publish them under
> http://developer.openstack.org/api-ref/networking/ .
> I sounds reasonable to me.
> 
> We can have a dedicated pages for each stadium project like networking-sfc
> like api-ref/networking/service-function-chaining.
> At now all APIs are placed under v2/ directory, but it is not good
> both from user and
> maintenance perspectives.
> 
> 
> So, the next thing we need to clarify is what names and directory
> structure are appropropriate
> from the documentation perspective.
> My proposal is to prepare a dedicated directory per networking project
> repository.
> The directory name should be a function name rather than a project
> name. For example,
> - neutron => ???
> - neutron-lbaas => load-balancer
> - neutron-vpnaas => vpn
> - neutron-fwaas => firewall
> - neutron-dynamic-routing => dynamic-routing
> - networking-sfc => service-function-chaining
> - networking-l2gw => layer2-gateway
> - (networking-bgpvpn) => bgp-vpn
> 
> My remaining open questions are:
> 
> - Is 'v2' directory needed?
>   All networking API provided by stadium projects are extensions to
> Networking v2 API and "v2" is the only API we have now.
>   Do we place all APIs from stadium projects under 'v2' directory, or
> is 'v2' directory unnecessary?

If we avoid the 'v2' directory perhaps we will be better prepared when we
adopt micro-versioning?

> 
> - what is a good name for main neutron API (provided by 'neutron' repo)?

core?
base?
neutron? :)

> 
> Any feedback would be appreciated.
> 
> Thanks,
> Akihiro
> 
>> Thanks,
>> Anne
>>
>>>
>>>
>>> --Projects not using common tooling--
>>> These projects have API docs but are not yet using the common tooling, as
>>> far as I can tell. Because of the user experience, I'm making a judgement
>>> call that these cannot be included in the common navigation. I have patched
>>> the projects.yaml file in the governance repo with the URLs I could
>>> screen-scrape, but if I'm incorrect please do patch the projects.yaml in the
>>> governance repo.
>>>
>>> astara
>>> cloudkitty
>>> congress
>>> magnum
>>> mistral
>>> monasca
>>> solum
>>> tacker
>>> trove
>>>
>>> Please reach out if you have questions or need assistance getting started
>>> with the new common tooling, documented here:
>>> http://docs.openstack.org/contributor-guide/api-guides.html.
>>>
>>> For searchlight, looking at http://developer.openstack.org/api-ref/search/
>>> they have the build job, but the info is not complete yet.
>>>
>>> One additional project I'm not sure what to do with is networking-nfc,
>>> since I'm not sure it is considered a neutron API. Can I get help to sort
>>> that question out?
>>>
>>> --Redirects from old pages--
>>> We have been adding .htaccess redirects from the old
>>> api-ref-servicename.html on developer.openstack.org as teams are comfortable
>>> with the accuracy of information and build stability. Please help out by
>>> patching the api-site repository's .htaccess file when you are ready to
>>> redirect. These projects could be ready for redirects but do not have them:
>>>
>>> designate
>>> glance
>>> heat
>>> sahara
>>> senlin
>>> swift
>>>
>>> I'm available for questions so please reach out as needed. I hope this
>>> covers our current status.
>>>
>>> A million thank yous to everyone who got us this far! Great teamwork,
>>> great docs work, great UI work, and great API work everyone.
>>> Anne
>>>
>>> --
>>> Anne Gentle
>>> www.justwriteclick.com
>>
>>
>>
>>
>> --
>> Anne Gentle
>> www.justwriteclick.com