<html>
<head>
<meta content="text/html; charset=windows-1252"
http-equiv="Content-Type">
</head>
<body bgcolor="#FFFFFF" text="#000000">
Current *-specs already include sections like "Data Model
Impact/REST Api Impact etc".<br>
So what about including a new section like "UseCase examples", which
can be updated as a separate patch once the associated CLI changes
are merged?<br>
<br>
Thanks,<br>
--Sridhar.<br>
<br>
<div class="moz-cite-prefix">On 11/27/2014 10:19 AM, Deepak Shetty
wrote:<br>
</div>
<blockquote
cite="mid:CAOXiiM=ZmHNuf1ZOf3q+Rrx-fy-n3ZO2L8+tnyNXpd2fb19jbQ@mail.gmail.com"
type="cite">
<div dir="ltr">But isn't *-specs comes very early in the process
where you have an idea/proposal of a feature, u don't have it
yet implemented. Hence specs just end up with Para's on how the
feature is supposed to work, but doesn't include any real world
screen shots as the code is not yet ready at that point of time.
Along with patch it would make more sense, since the author
would have tested it so it isn't a big overhead to catch those
cli screen shots and put it in a .txt or .md file so that patch
reviewers can see the patch in action and hence can review more
effectively<br>
<br>
thanx,<br>
deepak<br>
<br>
</div>
<div class="gmail_extra"><br>
<div class="gmail_quote">On Thu, Nov 27, 2014 at 8:30 AM, Dolph
Mathews <span dir="ltr"><<a moz-do-not-send="true"
href="mailto:dolph.mathews@gmail.com" target="_blank">dolph.mathews@gmail.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 class="gmail_extra"><br>
<div class="gmail_quote">
<div>
<div class="h5">On Wed, Nov 26, 2014 at 1:15 PM,
Steve Gordon <span dir="ltr"><<a
moz-do-not-send="true"
href="mailto:sgordon@redhat.com"
target="_blank">sgordon@redhat.com</a>></span>
wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0
0 .8ex;border-left:1px #ccc
solid;padding-left:1ex">
<div>
<div>----- Original Message -----<br>
> From: "Deepak Shetty" <<a
moz-do-not-send="true"
href="mailto:dpkshetty@gmail.com"
target="_blank">dpkshetty@gmail.com</a>><br>
> To: "OpenStack Development Mailing List
(not for usage questions)" <<a
moz-do-not-send="true"
href="mailto:openstack-dev@lists.openstack.org"
target="_blank">openstack-dev@lists.openstack.org</a>><br>
><br>
> Hi stackers,<br>
> I was having this thought which i
believe applies to all projects of<br>
> openstack (Hence All in the subject
tag)<br>
><br>
> My proposal is to have examples or
usecase folder in each project which has<br>
> info on how to use the
feature/enhancement (which was submitted as
part of<br>
> a gerrit patch)<br>
> In short, a description with screen
shots (cli, not GUI) which should be<br>
> submitted (optionally or mandatory)
along with patch (liek how testcases<br>
> are now enforced)<br>
><br>
> I would like to take an example to
explain. Take this patch @<br>
> <a moz-do-not-send="true"
href="https://review.openstack.org/#/c/127587/"
target="_blank">https://review.openstack.org/#/c/127587/</a>
which adds a default volume type<br>
> in Manila<br>
><br>
> Now it would have been good if we could
have a .txt or .md file alogn with<br>
> the patch that explains :<br>
><br>
> 1) What changes are needed in
manila.conf to make this work<br>
><br>
> 2) How to use the cli with this change
incorporated<br>
><br>
> 3) Some screen shots of actual usage
(Now the author/submitted would have<br>
> tested in devstack before sending
patch, so just copying those cli screen<br>
> shots wouldn't be too big of a deal)<br>
><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<br>
> lookign at test cases.<br>
> But i personally feel that those still
doesn't give a good visualization of<br>
> how a feature patch works in reality<br>
><br>
> Adding such a example/usecase file
along with patch helps in multiple ways:<br>
><br>
> 1) It helps the reviewer get a good
picture of how/which clis are affected<br>
> and how this patch fits in the flow<br>
><br>
> 2) It helps documentor get a good view
of how this patch adds value, hence<br>
> can document it better<br>
><br>
> 3) It may help the author or anyone
else write a good detailed blog post<br>
> using the examples/usecase as a
reference<br>
><br>
> 4) Since this becomes part of the patch
and hence git log, if the<br>
> feature/cli/flow changes in future, we
can always refer to how the feature<br>
> was designed, worked when it was first
posted by looking at the example<br>
> usecase<br>
><br>
> 5) It helps add a lot of clarity to the
patch, since we know how the author<br>
> tested it and someone can point missing
flows or issues (which otherwise<br>
> now has to be visualised)<br>
><br>
> 6) I feel this will help attract more
reviewers to the patch, since now its<br>
> more clear what this patch affects, how
it affects and how flows are<br>
> changing, even a novice reviewer can
feel more comfortable and be confident<br>
> to provide comments.<br>
><br>
> Thoughts ?<br>
<br>
</div>
</div>
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?<br>
</blockquote>
<div><br>
</div>
</div>
</div>
<div>+1 this is describing exactly what I expect out
of *-specs.</div>
<span class="">
<div> </div>
<blockquote class="gmail_quote" style="margin:0 0 0
.8ex;border-left:1px #ccc solid;padding-left:1ex">
<span><font color="#888888"><br>
-Steve<br>
</font></span>
<div>
<div><br>
_______________________________________________<br>
OpenStack-dev mailing list<br>
<a moz-do-not-send="true"
href="mailto:OpenStack-dev@lists.openstack.org"
target="_blank">OpenStack-dev@lists.openstack.org</a><br>
<a moz-do-not-send="true"
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>
</div>
</div>
</blockquote>
</span></div>
<br>
</div>
</div>
<br>
_______________________________________________<br>
OpenStack-dev mailing list<br>
<a moz-do-not-send="true"
href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><br>
<a moz-do-not-send="true"
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>
<br>
<fieldset class="mimeAttachmentHeader"></fieldset>
<br>
<pre wrap="">_______________________________________________
OpenStack-dev mailing list
<a class="moz-txt-link-abbreviated" href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a>
<a class="moz-txt-link-freetext" href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a>
</pre>
</blockquote>
<br>
</body>
</html>