On 09/13/2013 01:21 PM, Anne Gentle wrote:
On Fri, Sep 13, 2013 at 1:53 PM, Mike Asthalter
<mike.asthal...@rackspace.com <mailto:mike.asthal...@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 <annegen...@justwriteclick.com
<mailto:annegen...@justwriteclick.com>>
Reply-To: OpenStack Development Mailing List
<openstack-dev@lists.openstack.org
<mailto:openstack-dev@lists.openstack.org>>
Date: Thursday, September 12, 2013 11:32 PM
To: OpenStack Development Mailing List
<openstack-dev@lists.openstack.org
<mailto:openstack-dev@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
<mord...@inaugust.com <mailto:mord...@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@lists.openstack.org
<mailto:OpenStack-dev@lists.openstack.org>
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
--
Anne Gentle
annegen...@justwriteclick.com <mailto:annegen...@justwriteclick.com>
_______________________________________________
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
<mailto:OpenStack-dev@lists.openstack.org>
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
--
Anne Gentle
annegen...@justwriteclick.com <mailto:annegen...@justwriteclick.com>
_______________________________________________
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
_______________________________________________
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
