<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Wed, Mar 19, 2014 at 10:00 AM, Doug Hellmann <span dir="ltr"><<a href="mailto:doug.hellmann@dreamhost.com" target="_blank">doug.hellmann@dreamhost.com</a>></span> wrote:<br>

<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div style="font-size:small"><br></div><div class="gmail_extra">

<br><br><div class="gmail_quote"><div class="">On Wed, Mar 19, 2014 at 7:31 AM, Thierry Carrez <span dir="ltr"><<a href="mailto:thierry@openstack.org" target="_blank">thierry@openstack.org</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div>Kurt Griffiths wrote:<br>
> Kudos to Balaji for working so hard on this. I really appreciate his candid feedback on both frameworks.<br>
<br>
</div>Indeed, that analysis is very much appreciated.<br>
<br>
>From the Technical Committee perspective, we put a high weight on a<br>
factor that was not included in the report results: consistency and<br>
convergence between projects we commonly release in an integrated manner<br>
every 6 months. There was historically a lot of deviation, but as we add<br>
more projects that deviation is becoming more costly. We want developers<br>
to be able to jump from one project to another easily, and we want<br>
convergence from an operators perspective. </blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><br>



Individual projects are obviously allowed to pick the best tool in their<br>
toolbox. But the TC may also decide to let projects live out of the<br>
"integrated release" if we feel they would add too much divergence in.<br></blockquote><div><br></div></div><div><div style="font-size:small">As Thierry points out, an important aspect of being in the integrated release is being aligned with the rest of the community. The evaluation gives "community" considerations the lowest weight among the criteria considered. Does that ranking reflect the opinion of the entire Marconi team? If so, what benefits do you see to being integrated?</div>


<div style="font-size:small"><br></div><div style="font-size:small">The evaluation does not discuss any of the infrastructure tooling being built up around OpenStack's use of Pecan. For example, what will Marconi do for API documentation generation?</div>


<div style="font-size:small"><br></div></div></div></div></div></blockquote><div><br></div>Doug and I talked about this in #openstack-dev today, and I just wanted to point out that only one of nine integrated projects uses a Pecan-based solution for API documentation generation, using a tool called sphinxcontrib-docbookrestapi. [1]</div>

<div class="gmail_quote"><br></div><div class="gmail_quote">I consider this question a bit of a false representation of the direction we're going with API docs. There's no standard yet established other than "somehow create WADL so we can accurately represent a reference listing to users." Also with extensible APIs it might be easier to just maintain WADL, we just don't know until we get more data from more teams using the Sphinx extension. That said, we do use a common toolset to generate configuration reference information and I'd expect all integrated projects to save time and effort by standardizing as much as possible.<br>

</div><br class="">The Marconi team has had a tech writer assigned and the team is working within the guidelines we've given them.</div><div class="gmail_extra"><br></div><div class="gmail_extra">Thanks,</div><div class="gmail_extra">

Anne</div><div class="gmail_extra"><br></div><div class="gmail_extra">1. <a href="https://github.com/enovance/sphinxcontrib-docbookrestapi">https://github.com/enovance/sphinxcontrib-docbookrestapi</a> I'd like to rename it to sphinxcontrib-restapi or some such, since it doesn't generate docbook.<br>

<div class="gmail_quote"><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div class="gmail_extra">

<div class="gmail_quote"><div><div style="font-size:small"></div><div style="font-size:small">Pecan is currently gating changes against projects that use it, so we can be sure that changes to the framework do not break our applications. This does not appear to have been factored into the evaluation.</div>


</div><div class=""><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div><br>
> After reviewing the report below, I would recommend that Marconi<br>
> continue using Falcon for the v1.1 API and then re-evaluate Pecan for<br>
> v2.0 or possibly look at using swob.<br>
<br>
</div>The report (and your email below) makes a compelling argument that<br>
Falcon is a better match for Marconi's needs (or for a data-plane API)<br>
than Pecan currently is. My question would be, can Pecan be improved to<br>
also cover Marconi's use case ? Could we have the best of both worlds<br>
(an appropriate tool *and* convergence) ?<br></blockquote><div><br></div></div><div><div style="font-size:small">We had several conversations with Kurt and Flavio in Hong Kong about adding features to Pecan to support the Marconi team, and Ryan prototyped some of those changes shortly after we returned home. Was any of that work considered in the evaluation?</div>

<span class=""><font color="#888888">
<div style="font-size:small"><br></div><div style="font-size:small">Doug</div><div style="font-size:small"> <br></div></font></span></div><div class=""><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">



<br>
If the answer is "yes, probably", then it might be an option to delay<br>
inclusion in the integrated release so that we don't add (even<br>
temporary) divergence. If the answer is "definitely no", then we'll have<br>
to choose between convergence and functionality.<br>
<span><font color="#888888"><br>
--<br>
Thierry Carrez (ttx)<br>
<br>
_______________________________________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org" target="_blank">OpenStack-dev@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
</font></span></blockquote></div></div><br></div></div>
<br>_______________________________________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
<br></blockquote></div><br></div></div>