Open Stack

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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20141126/f2a36169/attachment.html>