Open Stack

On Wed, Mar 19, 2014 at 10:00 AM, Doug Hellmann <doug.hellmann at dreamhost.com
> wrote:

>
>
>
> On Wed, Mar 19, 2014 at 7:31 AM, Thierry Carrez <thierry at openstack.org>wrote:
>
>> Kurt Griffiths wrote:
>> > Kudos to Balaji for working so hard on this. I really appreciate his
>> candid feedback on both frameworks.
>>
>> Indeed, that analysis is very much appreciated.
>>
>> From the Technical Committee perspective, we put a high weight on a
>> factor that was not included in the report results: consistency and
>> convergence between projects we commonly release in an integrated manner
>> every 6 months. There was historically a lot of deviation, but as we add
>> more projects that deviation is becoming more costly. We want developers
>> to be able to jump from one project to another easily, and we want
>> convergence from an operators perspective.
>
>
>> Individual projects are obviously allowed to pick the best tool in their
>> toolbox. But the TC may also decide to let projects live out of the
>> "integrated release" if we feel they would add too much divergence in.
>>
>
> 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?
>
> 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?
>
>
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]

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.

The Marconi team has had a tech writer assigned and the team is working
within the guidelines we've given them.

Thanks,
Anne

1. https://github.com/enovance/sphinxcontrib-docbookrestapi I'd like to
rename it to sphinxcontrib-restapi or some such, since it doesn't generate
docbook.


> 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.
>
>
>>
>> > After reviewing the report below, I would recommend that Marconi
>> > continue using Falcon for the v1.1 API and then re-evaluate Pecan for
>> > v2.0 or possibly look at using swob.
>>
>> The report (and your email below) makes a compelling argument that
>> Falcon is a better match for Marconi's needs (or for a data-plane API)
>> than Pecan currently is. My question would be, can Pecan be improved to
>> also cover Marconi's use case ? Could we have the best of both worlds
>> (an appropriate tool *and* convergence) ?
>>
>
> 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?
>
> Doug
>
>
>>
>> If the answer is "yes, probably", then it might be an option to delay
>> inclusion in the integrated release so that we don't add (even
>> temporary) divergence. If the answer is "definitely no", then we'll have
>> to choose between convergence and functionality.
>>
>> --
>> Thierry Carrez (ttx)
>>
>> _______________________________________________
>> OpenStack-dev mailing list
>> OpenStack-dev at lists.openstack.org
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>
>
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140319/2aabdd1e/attachment.html>