Open Stack

On 09/13/2013 01:21 PM, Anne Gentle wrote:
>
>
>
> On Fri, Sep 13, 2013 at 1:53 PM, Mike Asthalter 
> <mike.asthalter at rackspace.com <mailto:mike.asthalter at rackspace.com>> 
> wrote:
>
>     Hi Anne,
>
>     I want to make sure I've understood the ramifications of your
>     statement about content sharing.
>
>     So for now, until the infrastructure team provides us with a
>     method to share content between repos, the only way to share the
>     content from the orchestration wadl with the api-ref
>     doc (https://github.com/openstack/heat/blob/master/doc/docbkx/api-ref/src/docbkx/api-ref.xml)
>     is to manually copy the content from the orchestration wadl to the
>     original heat wadl and then use that for the shared content. So we
>     will not delete the original heat wadl until that new method of
>     content sharing is in place. Is this correct?
>
>
> Hi Mike,
> It sounds like the dev team is fine with deleting that "original" heat 
> WADL and only maintaining one from here forward.
>
> The way they will control Icehouse edits to the heat WADL that 
> shouldn't yet be displayed to end users is to use the "Work In 
> Progress" button on review.openstack.org 
> <http://review.openstack.org>. When a patch is marked WIP, you can't 
> merge it.
>
> So, you can safely delete the original Heat WADL and then from your 
> dev guides, if you want to include a WADL, you can point to the one in 
> the api-site repository. We now have a mirror of the github.com 
> <http://github.com> repository at git.openstack.org 
> <http://git.openstack.org> that gives you access to the WADL in the 
> api-site repository at all times. I can walk you through building the 
> URL that points to the WADL file.
>

Anne,

Sorry for delay in response - I've been traveling.  I will submit a 
change to remove the wadl from the heat repo since  the api-site is 
finished.

Regards
-steve

> What we also need to build is logic in the build jobs so that any time 
> the api-site WADL is updated, your dev guide is also updated. This is 
> done in the Jenkins job in 
> https://github.com/openstack-infra/config/blob/master/modules/openstack_project/files/jenkins_job_builder/config/api-jobs.yaml. 
> I can either submit this patch for you, or I'll ask Steve or Zane to 
> do so.
>
> Hope this helps -
>
> Anne
>
>
>     Thanks!
>
>     Mike
>
>     From: Anne Gentle <annegentle at justwriteclick.com
>     <mailto:annegentle at justwriteclick.com>>
>     Reply-To: OpenStack Development Mailing List
>     <openstack-dev at lists.openstack.org
>     <mailto:openstack-dev at lists.openstack.org>>
>     Date: Thursday, September 12, 2013 11:32 PM
>     To: OpenStack Development Mailing List
>     <openstack-dev at lists.openstack.org
>     <mailto:openstack-dev at lists.openstack.org>>
>     Subject: Re: [openstack-dev] [Heat] Questions about plans for heat
>     wadls moving forward
>
>
>
>
>     On Thu, Sep 12, 2013 at 10:41 PM, Monty Taylor
>     <mordred at inaugust.com <mailto:mordred at inaugust.com>> wrote:
>
>
>
>         On 09/12/2013 04:33 PM, Steve Baker wrote:
>         > On 09/13/2013 08:28 AM, Mike Asthalter wrote:
>         >> Hello,
>         >>
>         >> Can someone please explain the plans for our 2 wadls moving
>         forward:
>         >>
>         >>   * wadl in original heat
>         >>     repo:
>         https://github.com/openstack/heat/blob/master/doc/docbkx/api-ref/src/wadls/heat-api/src/heat-api-1.0.wadl
>         >>    
>         <%22https://github.com/openstack/heat/blob/master/doc/docbkx/api-ref/src/wadls/heat-api/src/heat-api-1.>
>         >>   * wadl in api-site
>         >>     repo:https://github.com/openstack/api-site/blob/master/api-ref/src/wadls/orchestration-api/src/v1/orchestration-api.wadl
>         >>
>         > The original intention was to delete the heat wadl when the
>         api-site one
>         > became merged.
>
>
>     Sounds good.
>
>         >> 1. Is there a need to maintain 2 wadls moving forward, with the wadl
>         >> in the original heat repo containing calls that may not be
>         >> implemented, and the wadl in the api-site repo containing
>         implemented
>         >> calls only?
>         >>
>         >>     Anne Gentle advises as follows in regard to these 2 wadls:
>         >>
>         >>     "I'd like the WADL in api-site repo to be user-facing.
>         The other
>         >>     WADL can be truth if it needs to be a specification
>         that's not yet
>         >>     implemented. If the WADL in api-site repo is true and
>         implemented,
>         >>     please just maintain one going forward."
>         >>
>         >>
>         >> 2. If we maintain 2 wadls, what are the consequences
>         (gerrit reviews,
>         >> docs out of sync, etc.)?
>         >>
>         >> 3. If we maintain only the 1 orchestration wadl, how do we
>         want to
>         >> pull in the wadl content to the api-ref doc
>         >>
>         (https://github.com/openstack/heat/blob/master/doc/docbkx/api-ref/src/docbkx/api-ref.xml
>         >>
>         <%22https://github.com/openstack/heat/blob/master/doc/docbkx/api-ref/src/docb>)
>         >> from the orchestration wadl in the api-site repo: subtree merge, other?
>         >>
>         >>
>
>
>     Thanks Mike for asking these questions.
>
>     I've been asking the infrastructure team for help with pulling
>     content like the current nova request/response examples into the
>     api-site repo. No subtree merges please. We'll find some way.
>     Right now it's manual.
>
>         > These are good questions, and could apply equally to other out-of-tree
>         > docs as features get added during the development cycle.
>         >
>         > I still think that our wadl should live only in api-site.
>          If api-site
>         > has no branching policy to maintain separate Havana and Icehouse
>         > versions then maybe Icehouse changes should be posted as WIP
>         reviews
>         > until they can be merged.
>
>         I believe there is no branching in api-site because it's
>         describing API
>         and there is no such thing as a havana or icehouse version of
>         an API -
>         there are the API versions and they are orthogonal to server
>         release
>         versions. At least in theory. :)
>
>
>     Yep, that's our working theory. :)
>
>     Anne
>
>
>         _______________________________________________
>         OpenStack-dev mailing list
>         OpenStack-dev at lists.openstack.org
>         <mailto:OpenStack-dev at lists.openstack.org>
>         http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>
>
>
>     -- 
>     Anne Gentle
>     annegentle at justwriteclick.com <mailto:annegentle at justwriteclick.com>
>
>     _______________________________________________
>     OpenStack-dev mailing list
>     OpenStack-dev at lists.openstack.org
>     <mailto:OpenStack-dev at lists.openstack.org>
>     http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>
>
>
> -- 
> Anne Gentle
> annegentle at justwriteclick.com <mailto:annegentle at justwriteclick.com>
>
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20130920/c12dbd85/attachment-0001.html>