Current *-specs already include sections like "Data Model Impact/REST
Api Impact etc".
So what about including a new section like "UseCase examples", which can
be updated as a separate patch once the associated CLI changes are merged?
Thanks,
--Sridhar.
On 11/27/2014 10:19 AM, Deepak Shetty 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.math...@gmail.com <mailto:dolph.math...@gmail.com>> wrote:
On Wed, Nov 26, 2014 at 1:15 PM, Steve Gordon <sgor...@redhat.com
<mailto:sgor...@redhat.com>> wrote:
----- Original Message -----
> From: "Deepak Shetty" <dpkshe...@gmail.com
<mailto:dpkshe...@gmail.com>>
> To: "OpenStack Development Mailing List (not for usage
questions)" <openstack-dev@lists.openstack.org
<mailto:openstack-dev@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@lists.openstack.org
<mailto:OpenStack-dev@lists.openstack.org>
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
_______________________________________________
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
<mailto:OpenStack-dev@lists.openstack.org>
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
_______________________________________________
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
_______________________________________________
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
