Open Stack

On 05/09/2015 03:28 PM, Anne Gentle wrote:
> On Fri, May 8, 2015 at 12:26 PM, Monty Taylor <mordred at inaugust.com> wrote:
> 
>> On 05/07/2015 12:04 PM, Anne Gentle wrote:
>>> On Thu, May 7, 2015 at 9:12 AM, Ildikó Váncsa <
>> ildiko.vancsa at ericsson.com>
>>> wrote:
>>>
>>>>  Hi All,
>>>>
>>>>
>>>>
>>>> I missed the original thread with the registration to this list, so I
>> will
>>>> try to summarize my thoughts without history.
>>>>
>>>>
>>>>
>>>> First of all, I support the idea of generating the API Reference from
>> the
>>>> source code as that is the most up to date source of information. On the
>>>> other hand it makes much easier not just to create the exact document,
>> but
>>>> keep it up to date, which is unfortunately not true for some of the
>>>> projects that have their API guide in OpenStack Manuals.
>>>>
>>>>
>>>>
>>>> As for the format and placement, I think it can be an experimental
>> process
>>>> as it is described in the corresponding blueprint. As there are still
>>>> projects, which have their API documentation in the project tree it
>> shows
>>>> that it is a viable solution too to put more responsibility on the
>> project
>>>> teams as opposed to leaving all on the documentation team, which has
>>>> limited resources compared to the size of OpenStack at the moment.
>>>>
>>>>
>>>>
>>>> As I mentioned the documentation, which lives together with the code, it
>>>> raised a question for me. The API versioning is not always in line with
>> the
>>>> OpenStack releases neither with the changes on the API. As not every
>>>> project uses micro versioning or any kind of markup, which shows the
>>>> changes, it can mean that the v2 version of an API contains less
>> endpoints
>>>> in let’s Juno, than in Kilo. If we document and update the API Reference
>>>> based only on API versions, then we miss to capture the difference
>> between
>>>> the functionality covered in the different OpenStack releases. In case
>> of
>>>> those projects, which maintains their documentation together with the
>> code
>>>> base this should not be an issue, as the documentation is frozen on the
>>>> stable branches, when those are cut from master. What do you think about
>>>> this aspect? Is there a plan to address this issue too?
>>>>
>>>
>>> Great point Ildiko. I need to be clear in the spec that the intent is to
>>> have a "Kilo" Dev Guide, a "Juno" Dev Guide, probably just maintaining 2
>>> releases at a time (rather than the 3 that are security-supported). I
>> think
>>> it'll have to lag a release behind, so that Dev Guides are only available
>>> for already-released services.
>>>
>>> To keep the scope sane, I likely will start with Images v2.x API only.
>> I'm
>>> reaching out to that team to see if that's feasible.
>>>
>>> So it's not about the projects microversioning each resource call
>>> necessarily but about documenting "what can I do with a Juno-based cloud
>> as
>>> an app dev" -- and document ways to self-discover that also. In your
>> case,
>>> how would I know what calls are available in Juno, use stable branches? I
>>> guess I point the autodoc tool at the stable branch. Hm, this might mean
>>> some backported strings.
>>
>> I support more guides for app developers ... however, I'd like to be the
>> annoying person that points out that an app developer does not know or
>> care if the OpenStack cloud they are interacting with is running Juno or
>> not.
>>
>> I currently have credentials on 5 different public clouds. I do not know
>> what version of OpenStack is running on them. I do not want to know. I
>> certainly do not want to have to know.
>>
> 
> I absolutely agree that discoverability is part of this puzzle.
> 
> But in reading your response I can't help but think, where does upstream's
> responsibility stop and downstream's start? As in, even if I make great
> upstream dev guides, the devs still have to poke at the cloud they are
> consuming.

It's a tricky question for sure - but the more a dev has to poke at a
cloud vs. reading the upstream docs is the more, IMO, that we have
failed as OpenStack.

I earnestly believe that none of the downstream clouds should need docs
at all.

>>
>>> Each resource should have some indicator in the docs whether it's
>> available
>>> on Juno or Kilo, also. That's what's tougher for some APIs than others,
>>> right?
>>
>> The things an app developer needs to know are:
>>
>> - what version of the API is it in?
>> - how to discover what version of the API the cloud in question supports
>> - how to discover whether or not the cloud in question supports the feature
>>
>>
> Okay, so is it upstream's responsibility just to tell them the answers to
> these three questions, and that's it? The first question is fairly
> straightforward. The second is what I might say "not upstream doc's
> responsibility" though.

The second I think is upstreams - except that we don't this as
openstack. What I mean is, OpenStack should have a mechanism to learn
this, and upstream should document the _mechanism_ - and if we do that,
then it's clear on any given cloud how to find out the answers.

> So that's why we really need to work on the service catalog and why putting
> versions in endpoints is a bad deal for end users.

Well, I think that versions in endpoints is a red herring a bit -
although I agree with the sentiment.

Each service so far has implemented an endpoint which tells you what
versions the service supports ... but there's no way to get to it from
keystone catalog. *doh*

> And the third, why would an app dev look to upstream docs to answer that
> question? Wouldn't they look to their cloud provider?

What if they, as I now do, have 8 accounts on 8 different public clouds?
I shouldn't need to read docs on how to use UnitedStack or RunAbove
after I've used Dreamhost or Vexxhost.

(also, for the record, I have not needed to read ANY documentation for
any of the four clouds above - which is great, because unitedstack's
documentation is in Chinese)

>> As an example, Image API v1 and v2 support PUT as a mechanism to upload
>> images, but Rackspace cloud has it disabled as a deployment choice. I
>> have no idea which version of glance they're running, but with the above
>> information, I am able to use the Image API successfully.
>>
>>
> Right, and so Rackspace has a responsibility, sure. Does a Rackspace cloud
> user come to OpenStack docs? I know they do, but they do a comparison,
> which is still more time taken away from making a powerful app.

As a Rackspace cloud user, I use the OpenStack docs.

In fact, for the record, when I'm searching for the answer to something
and google tells me a Rackspace link, I deliberately ignore it and I go
to the Wonderful documentation that the OpenStack Docs team has made.

> So I guess what I still want to know is, what should upstream provide? Is
> the first question's answer, "What version of an API is it in" sufficient?
> With microversions and off/on configured capabilities, the version value
> alone is not sufficient.
> 
> So I guess I come back to, each call in upstream doc needs to indicate
> somehow when it was added, and how to tell if it's in the cloud you're
> using.

Yup.

Part of what I hope we get from defcore is less variability across our
clouds, so that, although we should have a mechanism to communicate
this, it's truly for edge cases - and not for essential things like
"upload an image"

> This is starting to feel less like a docs solution is sufficient and more
> like a standard usability solution is required. To me, that points to
> project-embedded solutions and consistency across all OpenStack APIs. I'll
> update the spec accordingly.

+100000000

(although figuring out the answer to your previous paragraph about
annotating when a thing started existing and how to learn if a cloud in
question has that thing)

>>> I really want to get the proof-of-concept robust enough to matter, so
>>> thanks for bringing up the versioning implications.
>>>
>>> Anne
>>>
>>>
>>>>
>>>>
>>>> Best Regards,
>>>>
>>>> Ildiko
>>>>
>>>> _______________________________________________
>>>> OpenStack-docs mailing list
>>>> OpenStack-docs at lists.openstack.org
>>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>>>>
>>>>
>>>
>>>
>>>
>>>
>>> _______________________________________________
>>> OpenStack-docs mailing list
>>> OpenStack-docs at lists.openstack.org
>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>>>
>>
>>
>> _______________________________________________
>> OpenStack-docs mailing list
>> OpenStack-docs at lists.openstack.org
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>>
> 
> 
>