openstack team mailing list archive

[Anne Gentle <anne@xxxxxxxxxxxxx>]

Hi Brian -
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?

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.

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.

Thanks,
Anne


Anne Gentle | http://justwriteclick.com/

[image: Facebook] <http://facebook.com/conversationandcommunity>[image:
Linkedin] <http://linkedin.com/annegentle>[image:
Twitter]<http://twitter.com/annegentle>


On Thu, Sep 8, 2011 at 3:52 PM, Brian Waldon <brian.waldon@xxxxxxxxxxxxx>wrote:

> 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.
>
> Waldon
>
>
> On Sep 7, 2011, at 7:57 AM, Anne Gentle wrote:
>
> Hello again -
> 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:
>
> compute-api
> identity-api (should this be auth-api?)
> image-api
> storage-api (should this be object-api?)
>
> Let me know your feedback on this naming standard.
>
> Thanks Jay for catching the keystone-api typo. :)
>
> Anne
>
> *Anne Gentle*
> anne@xxxxxxxxxxxxx
>  my blog <http://justwriteclick.com/> | my book<http://xmlpress.net/publications/conversation-community/>|
> LinkedIn <http://www.linkedin.com/in/annegentle> | Delicious<http://del.icio.us/annegentle>|
> Twitter <http://twitter.com/annegentle>
> On Tue, Sep 6, 2011 at 1:02 PM, Anne Gentle <anne@xxxxxxxxxxxxx> wrote:
>
>> Hi all -
>>
>> 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.
>>
>> Here is my current proposal, please feel free to suggest corrections as
>> you see fit.
>>
>> 1. Create new github repos named <project>-api that contain:
>> 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.
>>
>> 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.
>>
>> 3. Create a new github repo named openstack/openstack-manuals to contain
>> sys admin documentation such as the Admin manuals (installation,
>> configuration, administration docs).
>>
>> 4. Automated build/publish on Jenkins to the correct location on
>> docs.openstack.org (or project.openstack.org 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.
>>
>> 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.
>>
>> Thanks,
>> Anne
>>
>>
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack
> More help   : https://help.launchpad.net/ListHelp
> This email may include confidential information. If you received it in
> error, please delete it.
>
>
>
>
> --------------------------------------
> Brian Waldon
> Cloud Software Developer
> Rackspace Hosting
>
>
>