On Wed, Nov 26, 2014 at 1:15 PM, Steve Gordon <sgor...@redhat.com> wrote:
> ----- Original Message ----- > > From: "Deepak Shetty" <dpkshe...@gmail.com> > > To: "OpenStack Development Mailing List (not for usage questions)" < > 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 > 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