Open Stack

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 ?

thanx,
deepak
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20141126/4f1c4f75/attachment.html>