Re: [openstack-dev] [Heat] Questions about plans for heat wadls moving forward
Hi Anne Steve, I already have removing the original heal WADL in my work plan. I am just waiting for the released version of the clouddocs maven plugin to be fixed (1.10.0) to support pulling the wadl content into the api-ref doc (https://github.com/openstack/heat/blob/master/doc/docbkx/api-ref/src/docbkx/api-ref.xml) from the orchestration wadl in the api-ref site. Mike From: Steven Dake sd...@redhat.commailto:sd...@redhat.com Reply-To: OpenStack Development Mailing List openstack-dev@lists.openstack.orgmailto:openstack-dev@lists.openstack.org Date: Friday, September 20, 2013 2:46 PM To: OpenStack Development Mailing List openstack-dev@lists.openstack.orgmailto:openstack-dev@lists.openstack.org Cc: Anne Gentle annegen...@justwriteclick.commailto:annegen...@justwriteclick.com Subject: Re: [openstack-dev] [Heat] Questions about plans for heat wadls moving forward On 09/13/2013 01:21 PM, Anne Gentle wrote: On Fri, Sep 13, 2013 at 1:53 PM, Mike Asthalter mike.asthal...@rackspace.commailto: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.orghttp://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.comhttp://github.com repository at git.openstack.orghttp://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.commailto:annegen...@justwriteclick.com Reply-To: OpenStack Development Mailing List openstack-dev@lists.openstack.orgmailto:openstack-dev@lists.openstack.org Date: Thursday, September 12, 2013 11:32 PM To: OpenStack Development Mailing List openstack-dev@lists.openstack.orgmailto: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.commailto: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
Re: [openstack-dev] [Heat] Questions about plans for heat wadls moving forward
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
Re: [openstack-dev] [Heat] Questions about plans for heat wadls moving forward
We were successful yesterday in accessing the orchestration-api wadl in the api-site repo from the api-ref dev guide (https://github.com/openstack/heat/blob/master/doc/docbkx/api-ref/src/docbkx/api-ref.xml) in the original heat repo using the following syntax in the api-ref.xml doc: wadl:resources href=http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/orchestration-api/src/v1/orchestration-api.wadl; xmlns:wadl=http://wadl.dev.java.net/2009/02/ Therefore, as recommended in our discussion on this mailing list last week, I am planning to submit a patch to delete the original heat wadl (heat-api-1.0.wadl) and to point the api-ref.xml doc at the orchestration-api.wadl in the api-site repo, as shown above. Please let me know by tomorrow if anyone has any objections to deleting the original heat wadl, heat-api-1.0.wadl. On a related note, Anne Gentle has recommended the following: 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. Steve or Zane, is submitting this patch for the build logic something you would like to do, or should we ask Anne to take care of it? Mike From: Mike A mike.asthal...@rackspace.commailto:mike.asthal...@rackspace.com Reply-To: OpenStack Development Mailing List openstack-dev@lists.openstack.orgmailto:openstack-dev@lists.openstack.org Date: Friday, September 13, 2013 3:39 PM To: OpenStack Development Mailing List openstack-dev@lists.openstack.orgmailto:openstack-dev@lists.openstack.org Subject: Re: [openstack-dev] [Heat] Questions about plans for heat wadls moving forward Thanks for the clarification Anne! I will see you about building the URL for access to the wadl in the api-site repo from the dev guide next week. I think it's best to request Steve to submit the patch for logic in the build jobs to update the dev guide whenever the api-site wadl is updated, so he will be aware about it. Mike From: Anne Gentle annegen...@justwriteclick.commailto:annegen...@justwriteclick.com Reply-To: OpenStack Development Mailing List openstack-dev@lists.openstack.orgmailto:openstack-dev@lists.openstack.org Date: Friday, September 13, 2013 3:21 PM To: OpenStack Development Mailing List openstack-dev@lists.openstack.orgmailto:openstack-dev@lists.openstack.org Subject: Re: [openstack-dev] [Heat] Questions about plans for heat wadls moving forward On Fri, Sep 13, 2013 at 1:53 PM, Mike Asthalter mike.asthal...@rackspace.commailto: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.orghttp://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.comhttp://github.com repository at git.openstack.orghttp://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. 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.commailto:annegen...@justwriteclick.com Reply-To: OpenStack Development Mailing List openstack-dev@lists.openstack.orgmailto:openstack-dev@lists.openstack.org Date: Thursday, September 12, 2013 11:32 PM To: OpenStack Development Mailing List openstack-dev
Re: [openstack-dev] [Heat] Questions about plans for heat wadls moving forward
On 09/18/2013 08:09 AM, Mike Asthalter wrote: We were successful yesterday in accessing the orchestration-api wadl in the api-site repo from the api-ref dev guide (https://github.com/openstack/heat/blob/master/doc/docbkx/api-ref/src/docbkx/api-ref.xml) in the original heat repo using the following syntax in the api-ref.xml doc: wadl:resources href=http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/orchestration-api/src/v1/orchestration-api.wadl; xmlns:wadl=http://wadl.dev.java.net/2009/02/ Therefore, as recommended in our discussion on this mailing list last week, I am planning to submit a patch to delete the original heat wadl (heat-api-1.0.wadl) and to point the api-ref.xml doc at the orchestration-api.wadl in the api-site repo, as shown above. Please let me know by tomorrow if anyone has any objections to deleting the original heat wadl, heat-api-1.0.wadl. There is already a change in progress to delete all of heat's api-ref https://review.openstack.org/#/c/46412/ On a related note, Anne Gentle has recommended the following: 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. Steve or Zane, is submitting this patch for the build logic something you would like to do, or should we ask Anne to take care of it? I would think that there is no need at all now for heat/doc/docbkx/api-ref since it is part of api.site. Does this mean there is no need for an update job? ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Heat] Questions about plans for heat wadls moving forward
On 09/18/2013 12:37 PM, Mike Asthalter wrote: Hi Steve, Note that the two api-ref.xml docs in the two repos have /different/ purposes: * Heat repo: the api-ref.xml doc in this repo is the source for the *Orchestration API Dev Guide *(which I am planning to start working on), and provides detailed information and examples for each API call. You can see examples of these Dev Guides at docs.openstack.org, such as the OpenStack Compute API v2 and Extensions Reference at http://docs.openstack.org/api/openstack-compute/2/content/. I will be working on producing this doc for the Orchestration project. * Orchestration repo (api-site): the api-ref.xml doc in this repo is the source for the *API Complete Reference*, which provides a summary of all the calls for all the OpenStack products (http://api.openstack.org/api-ref.html). OK, thanks for the context - this would be a welcome addition. We need to support both of these moving forward, so I would prefer if you don't delete the files listed in your review (https://review.openstack.org/#/c/46412/) --- except please do delete the heat-api-1.0.wadl, which is no longer needed, since we now have the orchestration-api.wadl in the api-site repo. We need the other files to remain, since they provide the infrastructure for the Orchestration Dev Guide (pom.xml, api-ref.xml, and example files) that we need to produce. Consider this change abandoned, and feel free to set up the publishing job. cheers Mike From: Steve Baker sba...@redhat.com mailto:sba...@redhat.com Reply-To: OpenStack Development Mailing List openstack-dev@lists.openstack.org mailto:openstack-dev@lists.openstack.org Date: Wednesday, September 18, 2013 2:08 PM To: openstack-dev@lists.openstack.org mailto:openstack-dev@lists.openstack.org 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 09/18/2013 08:09 AM, Mike Asthalter wrote: We were successful yesterday in accessing the orchestration-api wadl in the api-site repo from the api-ref dev guide (https://github.com/openstack/heat/blob/master/doc/docbkx/api-ref/src/docbkx/api-ref.xml) in the original heat repo using the following syntax in the api-ref.xml doc: wadl:resources href=http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/orchestration-api/src/v1/orchestration-api.wadl; xmlns:wadl=http://wadl.dev.java.net/2009/02/ Therefore, as recommended in our discussion on this mailing list last week, I am planning to submit a patch to delete the original heat wadl (heat-api-1.0.wadl) and to point the api-ref.xml doc at the orchestration-api.wadl in the api-site repo, as shown above. Please let me know by tomorrow if anyone has any objections to deleting the original heat wadl, heat-api-1.0.wadl. There is already a change in progress to delete all of heat's api-ref https://review.openstack.org/#/c/46412/ On a related note, Anne Gentle has recommended the following: 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. Steve or Zane, is submitting this patch for the build logic something you would like to do, or should we ask Anne to take care of it? I would think that there is no need at all now for heat/doc/docbkx/api-ref since it is part of api.site. Does this mean there is no need for an update job? ___ 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
Re: [openstack-dev] [Heat] Questions about plans for heat wadls moving forward
On 13/09/13 05:41, Monty Taylor 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. +1 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? 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. :) Yes and no. When new API versions arrive, they always arrive with a particular release. So we do need some way to ensure the docs go live at the right time, but I think Steve's suggestion for handling that is fine. cheers, Zane. ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Heat] Questions about plans for heat wadls moving forward
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.xmlapplewebdata://ADF909E2-ABA6-4E57-81C2-41FC459CA6DF/%22https://github.com/openstack/heat/blob/master/doc/docbkx/api-ref/src/docb) 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? Thanks! Mike From: Anne Gentle annegen...@justwriteclick.commailto:annegen...@justwriteclick.com Reply-To: OpenStack Development Mailing List openstack-dev@lists.openstack.orgmailto:openstack-dev@lists.openstack.org Date: Thursday, September 12, 2013 11:32 PM To: OpenStack Development Mailing List openstack-dev@lists.openstack.orgmailto: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.commailto: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.orgmailto:OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev -- Anne Gentle annegen...@justwriteclick.commailto:annegen...@justwriteclick.com ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Heat] Questions about plans for heat wadls moving forward
On Fri, Sep 13, 2013 at 1:53 PM, Mike Asthalter 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. 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 repository at 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. 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 Reply-To: OpenStack Development Mailing List openstack-dev@lists.openstack.org Date: Thursday, September 12, 2013 11:32 PM To: OpenStack Development Mailing List 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.comwrote: 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 %22 https://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 %22 https://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
Re: [openstack-dev] [Heat] Questions about plans for heat wadls moving forward
Thanks for the clarification Anne! I will see you about building the URL for access to the wadl in the api-site repo from the dev guide next week. I think it's best to request Steve to submit the patch for logic in the build jobs to update the dev guide whenever the api-site wadl is updated, so he will be aware about it. Mike From: Anne Gentle annegen...@justwriteclick.commailto:annegen...@justwriteclick.com Reply-To: OpenStack Development Mailing List openstack-dev@lists.openstack.orgmailto:openstack-dev@lists.openstack.org Date: Friday, September 13, 2013 3:21 PM To: OpenStack Development Mailing List openstack-dev@lists.openstack.orgmailto:openstack-dev@lists.openstack.org Subject: Re: [openstack-dev] [Heat] Questions about plans for heat wadls moving forward On Fri, Sep 13, 2013 at 1:53 PM, Mike Asthalter mike.asthal...@rackspace.commailto: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.orghttp://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.comhttp://github.com repository at git.openstack.orghttp://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. 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.commailto:annegen...@justwriteclick.com Reply-To: OpenStack Development Mailing List openstack-dev@lists.openstack.orgmailto:openstack-dev@lists.openstack.org Date: Thursday, September 12, 2013 11:32 PM To: OpenStack Development Mailing List openstack-dev@lists.openstack.orgmailto: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.commailto: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
[openstack-dev] [Heat] Questions about plans for heat wadls moving forward
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 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? Please excuse if these questions have already been discussed. Thanks! Mike ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Heat] Questions about plans for heat wadls moving forward
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. 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? 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. ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Heat] Questions about plans for heat wadls moving forward
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. 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? 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. :) ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
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 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 %22 https://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 %22 https://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 http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev -- Anne Gentle annegen...@justwriteclick.com ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
