Open Stack

I'm not sure about making it mandatory, but I can certainly see the
benefits of doing this in some cases. Maybe we can start by creating the
area and making the doc optional, and allow reviews to ask for it to be
added where they consider it useful?

Sometimes (often in cinder), a feature gets written well before the
cinder-cli part gets written, but I guess you can still document via curl
or whatever testing mechanism you used - a separate patch can improve the
doc later once the cli part is written.

My one big worry, as with all documentation, is that we'll end up with a
large amount of stale documentation and nobody motivated to fix it.

On 27 November 2014 at 06:49, Deepak Shetty <dpkshetty at gmail.com> wrote:

> But isn't *-specs comes very early in the process where you have an
> idea/proposal of a feature, u don't have it yet implemented. Hence specs
> just end up with Para's on how the feature is supposed to work, but doesn't
> include any real world screen shots as the code is not yet ready at that
> point of time. Along with patch it would make more sense, since the author
> would have tested it so it isn't a big overhead to catch those cli screen
> shots and put it in a .txt or .md file so that patch reviewers can see the
> patch in action and hence can review more effectively
>
> thanx,
> deepak
>
>
> On Thu, Nov 27, 2014 at 8:30 AM, Dolph Mathews <dolph.mathews at gmail.com>
> wrote:
>
>>
>> On Wed, Nov 26, 2014 at 1:15 PM, Steve Gordon <sgordon at redhat.com> wrote:
>>
>>> ----- Original Message -----
>>> > From: "Deepak Shetty" <dpkshetty at gmail.com>
>>> > To: "OpenStack Development Mailing List (not for usage questions)" <
>>> openstack-dev at lists.openstack.org>
>>> >
>>> > Hi stackers,
>>> >    I was having this thought which i believe applies to all projects of
>>> > openstack (Hence All in the subject tag)
>>> >
>>> > My proposal is to have examples or usecase folder in each project
>>> which has
>>> > info on how to use the feature/enhancement (which was submitted as
>>> part of
>>> > a gerrit patch)
>>> > In short, a description with screen shots (cli, not GUI) which should
>>> be
>>> > submitted (optionally or mandatory) along with patch (liek how
>>> testcases
>>> > are now enforced)
>>> >
>>> > I would like to take an example to explain. Take this patch @
>>> > https://review.openstack.org/#/c/127587/ which adds a default volume
>>> type
>>> > in Manila
>>> >
>>> > Now it would have been good if we could have a .txt or .md file alogn
>>> with
>>> > the patch that explains :
>>> >
>>> > 1) What changes are needed in manila.conf to make this work
>>> >
>>> > 2) How to use the cli with this change incorporated
>>> >
>>> > 3) Some screen shots of actual usage (Now the author/submitted would
>>> have
>>> > tested in devstack before sending patch, so just copying those cli
>>> screen
>>> > shots wouldn't be too big of a deal)
>>> >
>>> > 4) Any caution/caveats that one has to keep in mind while using this
>>> >
>>> > It can be argued that some of the above is satisfied via commit msg and
>>> > lookign at test cases.
>>> > But i personally feel that those still doesn't give a good
>>> visualization of
>>> > how a feature patch works in reality
>>> >
>>> > Adding such a example/usecase file along with patch helps in multiple
>>> ways:
>>> >
>>> > 1) It helps the reviewer get a good picture of how/which clis are
>>> affected
>>> > and how this patch fits in the flow
>>> >
>>> > 2) It helps documentor get a good view of how this patch adds value,
>>> hence
>>> > can document it better
>>> >
>>> > 3) It may help the author or anyone else write a good detailed blog
>>> post
>>> > using the examples/usecase as a reference
>>> >
>>> > 4) Since this becomes part of the patch and hence git log, if the
>>> > feature/cli/flow changes in future, we can always refer to how the
>>> feature
>>> > was designed, worked when it was first posted by looking at the example
>>> > usecase
>>> >
>>> > 5) It helps add a lot of clarity to the patch, since we know how the
>>> author
>>> > tested it and someone can point missing flows or issues (which
>>> otherwise
>>> > now has to be visualised)
>>> >
>>> > 6) I feel this will help attract more reviewers to the patch, since
>>> now its
>>> > more clear what this patch affects, how it affects and how flows are
>>> > changing, even a novice reviewer can feel more comfortable and be
>>> confident
>>> > to provide comments.
>>> >
>>> > Thoughts ?
>>>
>>> I would argue that for the projects that use *-specs repositories this
>>> is the type of detail we would like to see in the specifications associated
>>> with the feature themselves rather than creating another separate
>>> mechanism. For the projects that don't use specs repositories (e.g. Manila)
>>> maybe this demand is an indication they should be considering them?
>>>
>>
>> +1 this is describing exactly what I expect out of *-specs.
>>
>>
>>>
>>> -Steve
>>>
>>> _______________________________________________
>>> 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
>>
>>
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>


-- 
Duncan Thomas
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20141127/1a7388e9/attachment.html>