On Fri, Mar 8, 2013 at 4:50 PM, Jeremy Stanley <[email protected]> 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 >
_______________________________________________ OpenStack-Infra mailing list [email protected] http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-infra
