Open Stack

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.mathews at gmail.com <mailto:dolph.mathews at gmail.com>> wrote:
>
>
>     On Wed, Nov 26, 2014 at 1:15 PM, Steve Gordon <sgordon at redhat.com
>     <mailto:sgordon at redhat.com>> wrote:
>
>         ----- Original Message -----
>         > From: "Deepak Shetty" <dpkshetty at gmail.com
>         <mailto:dpkshetty at gmail.com>>
>         > To: "OpenStack Development Mailing List (not for usage
>         questions)" <openstack-dev at lists.openstack.org
>         <mailto: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
>         <mailto: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
>     <mailto: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/20141128/2e79e0e7/attachment.html>