Open Stack

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
>>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-infra/attachments/20130308/4fc26426/attachment-0001.html>