Open Stack

On Fri, Mar 8, 2013 at 7:32 PM, Anne Gentle <anne at openstack.org> wrote:

>
>
>
> On Fri, Mar 8, 2013 at 3:38 PM, Laura Alves <laura.adq at gmail.com> wrote:
>
>>
>>
>> On Fri, Mar 8, 2013 at 4:50 PM, Jeremy Stanley <fungi at yuggoth.org> wrote:
>>
>>> I'm Cc'ing you to be on the safe side because I'm unsure whether
>>> you're subscribed to the list. Forgive me for the duplicate reply if
>>> you are!
>>>
>>> No problem, thanks! I'm, but I forgot to add Anne. Sorry!
>>
>>
>
> Thanks for looping me in!
>
>
>>  On 2013-03-08 00:01:46 -0300 (-0300), Laura Alves wrote:
>>> [...]
>>> > Currently, the API samples we use to document are the ones added
>>> > by developers to their respective repo doc folders (commonly
>>> > 'repo'/doc/api_samples/'api_name'. So what we're doing when
>>> > documenting a new API (or updating the samples of an existing one)
>>> > is basically downloading the new files and adding them to our
>>> > commit, so then they are merged to the API-site repo. Certainly
>>> > having the files copied from one repo to another this way is a big
>>> > part of the work, and not a super-fun one.
>>> [...]
>>>
>>> Would it be possible for the API doc jobs to just retrieve an
>>> up-to-date git clone of whatever project/branch they're documenting
>>> at build time? Or would it maybe make more sense to merge the API
>>> documentation into the projects they're documenting and simply
>>> generate updated API documentation as a publish job out of the post
>>> queue for each commit? I mainly just want to make sure that we're
>>> not simply codifying a particular human workflow which might not
>>> actually be well suited to automation.
>>>
>>>
> I think that an automation of a git clone would work. There may be one
> additional automation that would help achieve the end-goal.
>
> The blueprint/discussion for this is here:
> https://blueprints.launchpad.net/openstack-manuals/+spec/api-samples-to-api-site
>
> The main idea is to ensure the most updated samples are available to the
> docs site. I think the workflow should be:
>
> 1. A nova dev makes new template files for API samples, checks into nova
> repo.
>  2. Devs do the review process on nova repo, approve the patch.
> 3. At merge time, api_samples are built from templates (I don't believe
> this is automated currently, Sean Dague has to remind nova devs to make
> sure samples are built, possibly this could happen prior to approval).
> 4. At merge time, git clone the api_samples directory to the api-site repo
> into the correct directory.
>
> Seem like a good workflow or too much robot?
>
> Anne
>
>
>
>>  If there are technical or policy reasons to have these files
>>> duplicated but kept in sync between projects, then it may be
>>> possible to make a job triggered from merges to one project
>>> automatically propose changes to another. That definitely sounds
>>> hacky to me, though, if it can be avoided at all through
>>> reorganization of those projects to avoid that duplication in the
>>> first place.
>>>
>>>
>> I agree, I don't want to automatize this more than necessary or
>> recommended. My main concern is to get these new samples available to the
>> api-site repo in the most lightweight and less troubling way, even if it's
>> a one-time solution, at least for now.
>>
>> I wouldn't have any problems with coping and checking the current samples
>> myself, but I'd still like to see if there is a possible solution for the
>> upcoming samples by reorganizing / improving some processes, even if it's
>> not on the infra side (you still have a better view of the big picture).
>> I'm really not a fan of duplicating stuff neither, but I personally like
>> less the idea of merging repos with samples which have not been checked for
>> consistency by the doc team.
>>
>> > I thought outlining this through email would be better to reach
>>> > everyone despite the time zones, but I'll be totally available to
>>> > continue the discussion in the infra channel (I won't be this
>>> > sleepy, hopefully).
>>>
>>> Yes, the easiest times to reach the bulk of our Infra core
>>> developers on IRC tend to be between 1700-0300 UTC on weekdays, but
>>> we're often around at other times as well (I tend to be on starting
>>> at about 1300 UTC for example).
>>>
>>> Cool, I'm not sure that what I've said makes any sense at this point, so
>> I'll be bothering over there too :D
>>
>> Thanks!
>> ladquin
>>
>>
>>> --
>>> Jeremy Stanley
>>>
>>
>>
>
Today with Anne we discussed also the possibility of going the other way
around with the API site: instead of moving the samples to our doc repo,
we'd move our wadl's, xml's and any other needed files to each API project
repo, and then we'd have "one-page-per-api" instead of the long, growing
one we have now.
>From the Jenkins side, it shouldn't be a problem (I think), it would
required as many jobs as API pages we need to publish.

I like this approach for some reasons:
- It's one step forward to some level of automation regarding API
publishing.
- It will be "cleaner" in from the repo/jenkins' jobs point of view: no
hacky or duplicated stuff.
- The API catalog is growing constantly, the page is getting bulky,
splitting it up may allow some aesthetic / maintaining improvements.

 There are some other issues we're still to find out / discuss:
- Devs will have to review/approve API doc patches.  Doc'ers (!) may need
to approve their new API samples (not sure about this).
- It is more work than the original idea (though, if it works, the benefits
in the long run will be bigger)
- Some other technical point that has just left my mind (Sorry, I shouldn't
write emails after midnight).

As usual, comments, questions and corrections are welcome!

Thanks!
ladquin
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-infra/attachments/20130312/3da1ea72/attachment.html>