Hi Brian - <br>The original goal for moving these over to separate repos is to govern
the APIs (implementation, not just docs) with votes from the core team, not just one person. The naming convention (adding -docs) for these projects depends on the purpose for the repository. This dependency is at the heart of the debate about API and docs - does the doc say what should be, or what is? Until the docs live within an implementation, documenting what is reality, we have a separation of docs from API. I'd prefer they live a bit closer together. Can that happen for all the projects? <br>
<br>One bit of tooling that we have access to is an RST to DocBook tool, so for the Image API I take the RST that the devs write and turn it into DocBook. For the Identity API, they are embedding WADLs that document the API so we are able to embed the doc with the code a little closer. I'd love to hear of ideas for additional steps we can take so that the docs are created from code or live as closely to code as possible. <br>
<br>As for renaming the three that exist (three migrations in a week, whew!), let's talk some more about what lives in those repos and what the PPB would like for projects to strive for. We can rename, sure. Completely understand the potential for confusion here. Let's talk about the main goal some more though before we go through a rename process.<br>
<br>Thanks,<br>Anne<br><br><br><div id="WISESTAMP_SIG_2258"><div style="font-size: 13.3px; font-family: Verdana,Arial,Helvetica,sans-serif;"><div style="margin: 0pt 0pt 8px;"><div style="text-align: left;"><span style="font-size: xx-small;"><span style="font-family: verdana,sans-serif; font-weight: bold; color: rgb(51, 51, 51);"><span style="color: rgb(102, 102, 102);">Anne Gentle</span></span></span> <span style="font-size: xx-small;"><span style="color: rgb(255, 0, 0);">| </span></span><span style="font-family: Arial,Helvetica,Geneva,Sans-Serif; color: rgb(0, 0, 0); font-size: xx-small;"><a href="http://justwriteclick.com/" target="_blank">http://justwriteclick.com/</a></span></div>
<p style="margin: 0pt;"><a style="padding: 0pt 2px;" href="http://facebook.com/conversationandcommunity" target="_blank"><img style="vertical-align: middle;" src="http://www.images.wisestamp.com/facebook.png" alt="Facebook" border="0" height="16" width="16"></a><a style="padding: 0pt 2px;" href="http://linkedin.com/annegentle" target="_blank"><img style="vertical-align: middle;" src="http://www.images.wisestamp.com/linkedin.png" alt="Linkedin" border="0" height="16" width="16"></a><a style="padding: 0pt 2px;" href="http://twitter.com/annegentle" target="_blank"><img style="vertical-align: middle;" src="http://www.images.wisestamp.com/twitter.png" alt="Twitter" border="0" height="16" width="16"></a></p>
<div style="clear: both;"></div></div><img src="http://p1.wisestamp.com/pixel.png?p=mozilla&v=2.7.4&t=1315753538219&u=755481b20c4ca423" height="1" width="1"></div></div><br><br><div class="gmail_quote">On Thu, Sep 8, 2011 at 3:52 PM, Brian Waldon <span dir="ltr"><<a href="mailto:brian.waldon@mailtrust.com">brian.waldon@mailtrust.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;"><div style="word-wrap: break-word;">Would it make more sense to call the repos compute-api-docs, identity-api-docs, etc? I just saw the 'identity-api' repo get created an I immediately thought that is where the spec implementation lived.<div>
<br></div><div>Waldon<br><div><br></div><div><br><div><div><div></div><div class="h5"><div>On Sep 7, 2011, at 7:57 AM, Anne Gentle wrote:</div><br></div></div><blockquote type="cite"><div><div></div><div class="h5">Hello again - <br>
In yesterday's team meeting, Brian Lamar brought up a good point - why name the API projects after the project name, why not the product name? This makes a lot of sense to me. So the names for the API repos will be:<br>
<br>compute-api<br>identity-api (should this be auth-api?)<br>image-api<br>storage-api (should this be object-api?)<br><br>Let me know your feedback on this naming standard.<br><br>Thanks Jay for catching the keystone-api typo. :) <br>
<br>Anne<br><br><div style="margin: 2em 0pt;" name="sig_d41d8cd98f"><div style="padding: 5px; font-size: 11px; color: rgb(102, 102, 102); font-family: sans-serif;">
<font><b>Anne Gentle</b>
<br>
<a href="mailto:anne@openstack.org" target="_blank">anne@openstack.org</a><br>
</font><div style="font-size: 10px;">
<font><a href="http://justwriteclick.com/" target="_blank">my blog</a> |
<a href="http://xmlpress.net/publications/conversation-community/" target="_blank">my book</a> |
<a href="http://www.linkedin.com/in/annegentle" target="_blank"><span>LinkedIn</span></a> | <a href="http://del.icio.us/annegentle" target="_blank">Delicious</a> |
<a href="http://twitter.com/annegentle" target="_blank">Twitter</a>
</font></div></div></div><div class="gmail_quote">On Tue, Sep 6, 2011 at 1:02 PM, Anne Gentle <span dir="ltr"><<a href="mailto:anne@openstack.org" target="_blank">anne@openstack.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
Hi all -<br><br>I wanted to discuss some changes to the API documentation for each project prior to implementation to make sure I'm not missing any crucial detail and to ensure you all feel you have ownership of the solution and input into it. My goal is to move all the OpenStack documentation into github repos. In doing so, I will also move all the API documentation into separate repos with a goal of completing the move by October 1st.<br>
<br>Here is my current proposal, please feel free to suggest corrections as you see fit. <br><br>1. Create new github repos named <project>-api that contain:<br>API documentation including existing API Dev Guides and in the case of Nova, an API Spec. Four new projects for now: openstack/glance-api, openstack/keystone, openstack/nova-api, openstack/swift-api. <br>
<br>2. Create connection to Gerrit for review by core devs for each project, plus the creation of a new group, openstack-core-doc, for reviews of all four projects.<br><br>3. Create a new github repo named openstack/openstack-manuals to contain sys admin documentation such as the Admin manuals (installation, configuration, administration docs).<br>
<br>4. Automated build/publish on Jenkins to the correct location on <a href="http://docs.openstack.org/" target="_blank">docs.openstack.org</a> (or <a href="http://project.openstack.org/" target="_blank">project.openstack.org</a> as appropriate), either /diablo or /api or /incubation depending on project's state. Also includes Jenkins jobs to validate the docs pre-merge, for XML validation and testing for missing figures.<br>
<br>Please give me your feedback by the end of this week so we can make the next moves. Ha! Move! I've also added this item for discussion at today's team meeting. <br><br>Thanks,<br>Anne<br><font color="#888888"><br>
</font></blockquote></div><br></div></div><div class="im">
_______________________________________________<br>Mailing list: <a href="https://launchpad.net/%7Eopenstack" target="_blank">https://launchpad.net/~openstack</a><br>Post to : <a href="mailto:openstack@lists.launchpad.net" target="_blank">openstack@lists.launchpad.net</a><br>
Unsubscribe : <a href="https://launchpad.net/%7Eopenstack" target="_blank">https://launchpad.net/~openstack</a><br>More help : <a href="https://help.launchpad.net/ListHelp" target="_blank">https://help.launchpad.net/ListHelp</a><br>
</div><div class="im">This email may include confidential information. If you received it in error, please delete it.<br></div></blockquote></div><br><div>
<span style="border-collapse: separate; color: rgb(0, 0, 0); font-family: Helvetica; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; font-size: medium;"><div style="word-wrap: break-word;">
<br><br></div><div style="word-wrap: break-word;">--------------------------------------<br><font color="#888888">Brian Waldon<br>Cloud Software Developer<br>Rackspace Hosting<br><br></font></div></span>
</div>
<br></div></div></div></blockquote></div><br>