<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/">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>