<div dir="ltr"><div><div><div>Hi Valeriy,<br></div> I know about docs, but this was a proposal to provide small doc which are patch specific as that helps reviewers and other doc writers<br></div><br>I have many a times seen people asking on IRC or list on how to test this patch, or i did this with your patch but didn't work , such iterations can be reduced if we can have small docs (in free flowing text to begin with) associated with each patch than can help people other than author to understand what/how the patch adds functionality, which will improve the overall review quality and reviewers in general<br><br></div>thanx,<br>deepak<br>P.S. I took the Manila patch just as an example , nothing specific about it :)<br><div><br></div></div><div class="gmail_extra"><br><div class="gmail_quote">On Wed, Nov 26, 2014 at 3:40 PM, Valeriy Ponomaryov <span dir="ltr"><<a href="mailto:vponomaryov@mirantis.com" target="_blank">vponomaryov@mirantis.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div>Hi Deepak,</div><div><br></div><div>Docs are present in any project already, according to example with manila - <a href="https://github.com/openstack/manila/tree/master/doc/source" target="_blank">https://github.com/openstack/manila/tree/master/doc/source</a></div><div><br></div><div>It is used for docs on <a href="http://docs.openstack.org/" target="_blank">http://docs.openstack.org/</a> , also everyone if able to contribute to it.</div><div><br></div><div>See docs built on basis of files from manila repo: <a href="http://docs.openstack.org/developer/manila/" target="_blank">http://docs.openstack.org/developer/manila/</a></div><div><br></div><div>For most of projects we have already useful resource: <a href="http://docs.openstack.org/cli-reference/content/" target="_blank">http://docs.openstack.org/cli-reference/content/</a></div><div><br></div><div>In conclusion I can say that it is question more to the organization of creation such docs than possibility to create it in general.</div><div><br></div><div>Regards,</div><div>Valeriy Ponomaryov</div><div class="gmail_extra"><br><div class="gmail_quote"><div><div class="h5">On Wed, Nov 26, 2014 at 8:01 AM, Deepak Shetty <span dir="ltr"><<a href="mailto:dpkshetty@gmail.com" target="_blank">dpkshetty@gmail.com</a>></span> wrote:<br></div></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div><div class="h5"><div dir="ltr"><div><div><div><div><div><div><div><div><div><div><div><div><div><div><div><div>Hi stackers,<br></div> I was having this thought which i believe applies to all projects of openstack (Hence All in the subject tag)<br><br></div>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)<br></div><div>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)<br></div><div><br></div>I would like to take an example to explain. Take this patch @ <a href="https://review.openstack.org/#/c/127587/" target="_blank">https://review.openstack.org/#/c/127587/</a> which adds a default volume type in Manila<br><br></div>Now it would have been good if we could have a .txt or .md file alogn with the patch that explains :<br><br></div>1) What changes are needed in manila.conf to make this work<br></div><br>2) How to use the cli with this change incorporated<br></div><br>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)<br></div><br>4) Any caution/caveats that one has to keep in mind while using this<br><br>It can be argued that some of the above is satisfied via commit msg and lookign at test cases.<br>But i personally feel that those still doesn't give a good visualization of how a feature patch works in reality<br><br></div>Adding such a example/usecase file along with patch helps in multiple ways:<br><br></div>1) It helps the reviewer get a good picture of how/which clis are affected and how this patch fits in the flow<br></div><br>2) It helps documentor get a good view of how this patch adds value, hence can document it better<br></div><br>3) It may help the author or anyone else write a good detailed blog post using the examples/usecase as a reference<br></div><br>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<br></div><br>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)<br></div><br>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.<br><br></div>Thoughts ?<br><br>thanx,<br>deepak<br><br></div>
<br></div></div>_______________________________________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org" target="_blank">OpenStack-dev@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
<br></blockquote></div><span class="HOEnZb"><font color="#888888"><br><br clear="all"><div><br></div>-- <br><div><div dir="ltr">Kind Regards<br>Valeriy Ponomaryov<br><a href="http://www.mirantis.com" target="_blank">www.mirantis.com</a><br><a href="mailto:vponomaryov@mirantis.com" target="_blank">vponomaryov@mirantis.com</a><br></div></div>
</font></span></div></div>
<br>_______________________________________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
<br></blockquote></div><br></div>