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] What's Up Doc? Sep 18 2013
Just a couple notes about #5 (inking to WADL files in separate repositories): 1. This feature in supported in version 1.10.0 of the clouddocs maven plugin, which has now been reverted back to 1.9.3 due to request/response issues. You should be able to test using 1.9.4-SNAPSHOT until version 1.10.0 is available again. 2. You must use a plain URL to access the wadl. See the following example. For example, to get the plain version for the following URL: http://git.openstack.org/cgit/openstack/api-site/tree/api-ref/src/wadls/orchestration-api/src/v1/orchestration-api.wadl Browse to the above location in Firefox, and then click (plainhttp://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/orchestration-api/src/v1/orchestration-api.wadl) on the blob: line, just above where the wadl text appears. This will display the plain version of the URL: http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/orchestration-api/src/v1/orchestration-api.wadl Then use the plain version of the URL to access the wadl resources in the API Devguide: 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/ Mike From: Anne Gentle a...@openstack.orgmailto:a...@openstack.org Reply-To: OpenStack Development Mailing List openstack-dev@lists.openstack.orgmailto:openstack-dev@lists.openstack.org Date: Wednesday, September 18, 2013 8:36 PM To: openstack-d...@lists.openstack.orgmailto:openstack-d...@lists.openstack.org openstack-d...@lists.openstack.orgmailto:openstack-d...@lists.openstack.org, OpenStack Development Mailing List openstack-dev@lists.openstack.orgmailto:openstack-dev@lists.openstack.org Cc: Glen Campbell glen.campb...@rackspace.commailto:glen.campb...@rackspace.com Subject: [openstack-dev] What's Up Doc? Sep 18 2013 Less than a month until the Oct. 17th timed release! We're in better shape than in past releases but the install guide consolidation is crucial and there are many doc bugs. It's crunch time! 1. In review and merged this past week: Congrats to Michael Still for his first doc patches to openstack-manuals! He got his new skillz at boot camp. Thanks for the patches! I see good doc bug fixes going in, and Tom put in an update to the auto-generated tables. We had a lot of cleanup to do for the flattening of directories but I think it has mostly settled now. The last step is to move the Networking Admin Guide's content into the correct locations (install or config or admin). Nermina's on it, assigned to bug https://bugs.launchpad.net/openstack-manuals/+bug/1223542. Andreas has a good Etherpad going to talk about continuous publishing: https://etherpad.openstack.org/Continous_Publishing. It's possible we'll need to release the Cloud Admin Guide as well due to many references to configuration files. Please join in the discussion as we only have less than a month until release! 2. High priority doc work: The install guide remains a high priority as do doc bugs. Shaun is working on a patch this week to consolidate the basic-install to create one single-sourced install-guide (which will document for yum, apt, and zypper). There were over 300 doc bugs in openstack-manuals earlier this week as some docimpact bugs got logged, but we are making decent progress. We also need to have someone re-run the autodoc tables and try to match up with some of the storage patches in this week: https://review.openstack.org/#/c/47044/ and https://review.openstack.org/#/c/47118/. 3. Doc work going on that I know of: Kersten Richter is working on the Compute API docs again and getting an environment set up. 4. New incoming doc requests: At the Doc Boot Camp, Joe Gordon asked me to write up a checklist of sorts for what info should go along with a DocImpact flag. I wrote up my ideas in a blog post and would love more input before putting it on the wiki. http://justwriteclick.com/2013/09/17/openstack-docimpact-flag-walk-through/ 5. Doc tools updates: We had a 1.10.0 release today but had to revert back to 1.9.3 due to the request/responses not appearing in the API reference page. David Cramer's aware of the problem and will work through it. We also had a breakthrough where we can now link to WADL files in separate repositories so we have a single source of truth. Thanks to Mike Asthalter for testing! He reported that you can use this syntax in the xml doc where you want to refer to the WADL: 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/ 6. Other doc news: We had a great time at Docs Boot Camp. I wrote up a blog entry and posted some pictures: http://justwriteclick.com/2013/09/13/openstack-docs-boot-camp-wrap-up/ https
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
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
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
