<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Fri, Mar 8, 2013 at 3:38 PM, Laura Alves <span dir="ltr"><<a href="mailto:laura.adq@gmail.com" target="_blank">laura.adq@gmail.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><br><br><div class="gmail_quote">On Fri, Mar 8, 2013 at 4:50 PM, Jeremy Stanley <span dir="ltr"><<a href="mailto:fungi@yuggoth.org" target="_blank">fungi@yuggoth.org</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
I'm Cc'ing you to be on the safe side because I'm unsure whether<br>
you're subscribed to the list. Forgive me for the duplicate reply if<br>
you are!<br>
<br></blockquote><div>No problem, thanks! I'm, but I forgot to add Anne. Sorry!<br> <br></div></div></blockquote><div><br></div><div>Thanks for looping me in! <br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<div class="gmail_quote"><div></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
On 2013-03-08 00:01:46 -0300 (-0300), Laura Alves wrote:<br>
[...]<br>
<div>> Currently, the API samples we use to document are the ones added<br>
> by developers to their respective repo doc folders (commonly<br>
> 'repo'/doc/api_samples/'api_name'. So what we're doing when<br>
> documenting a new API (or updating the samples of an existing one)<br>
> is basically downloading the new files and adding them to our<br>
> commit, so then they are merged to the API-site repo. Certainly<br>
> having the files copied from one repo to another this way is a big<br>
> part of the work, and not a super-fun one.<br>
</div>[...]<br>
<br>
Would it be possible for the API doc jobs to just retrieve an<br>
up-to-date git clone of whatever project/branch they're documenting<br>
at build time? Or would it maybe make more sense to merge the API<br>
documentation into the projects they're documenting and simply<br>
generate updated API documentation as a publish job out of the post<br>
queue for each commit? I mainly just want to make sure that we're<br>
not simply codifying a particular human workflow which might not<br>
actually be well suited to automation.<br>
<br></blockquote></div></blockquote><div><br></div><div>I think that an automation of a git clone would work. There may be one additional automation that would help achieve the end-goal.<br><br></div><div>The blueprint/discussion for this is here: <a href="https://blueprints.launchpad.net/openstack-manuals/+spec/api-samples-to-api-site">https://blueprints.launchpad.net/openstack-manuals/+spec/api-samples-to-api-site</a><br>
<br></div><div>The main idea is to ensure the most updated samples are available to the docs site. I think the workflow should be:<br><br>1. A nova dev makes new template files for API samples, checks into nova repo.<br>
</div>
<div>2. Devs do the review process on nova repo, approve the patch.<br></div><div>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).<br>
</div><div>4. At merge time, git clone the api_samples directory to the api-site repo into the correct directory.<br><br></div><div>Seem like a good workflow or too much robot?<br><br>Anne<br><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
If there are technical or policy reasons to have these files<br>
duplicated but kept in sync between projects, then it may be<br>
possible to make a job triggered from merges to one project<br>
automatically propose changes to another. That definitely sounds<br>
hacky to me, though, if it can be avoided at all through<br>
reorganization of those projects to avoid that duplication in the<br>
first place.<br>
<div><br></div></blockquote><div><br>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.<br><br>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. <br><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div>
> I thought outlining this through email would be better to reach<br>
> everyone despite the time zones, but I'll be totally available to<br>
> continue the discussion in the infra channel (I won't be this<br>
> sleepy, hopefully).<br>
<br>
</div>Yes, the easiest times to reach the bulk of our Infra core<br>
developers on IRC tend to be between 1700-0300 UTC on weekdays, but<br>
we're often around at other times as well (I tend to be on starting<br>
at about 1300 UTC for example).<br>
<span><font color="#888888"><br></font></span></blockquote><div>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<br><br>Thanks!<br>ladquin<span class=""><font color="#888888"><br>
</font></span></div><span class=""><font color="#888888"><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><span><font color="#888888">
--<br>
Jeremy Stanley<br>
</font></span></blockquote></font></span></div><br>
</blockquote></div><br></div></div>