Open Stack

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!


> 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.
>
> 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/7035af48/attachment.html>