X-MimeOLE: Produced By Microsoft Exchange V6.5
Received: by onstor-exch02.onstor.net 
	id <01C75F5E.019FB362@onstor-exch02.onstor.net>; Mon, 5 Mar 2007 11:39:36 -0800
MIME-Version: 1.0
Content-Type: multipart/alternative;
	boundary="----_=_NextPart_001_01C75F5E.019FB362"
Content-class: urn:content-classes:message
Subject: RE: CLI Refactoring Functional Spec
Date: Mon, 5 Mar 2007 11:39:35 -0800
Message-ID: <BB375AF679D4A34E9CA8DFA650E2B04E02A95BCB@onstor-exch02.onstor.net>
In-Reply-To: <A5437B3F-8053-409A-B2AD-1F3BEB6A5990@onstor.com>
X-MS-Has-Attach: 
X-MS-TNEF-Correlator: 
Thread-Topic: CLI Refactoring Functional Spec
Thread-Index: AcdfWDRSUrfjMlC2SpG24eEuyVrxOgAAIURQ
From: "Charissa Willard" <charissa.willard@onstor.com>
To: "Ian Brown" <ian.brown@onstor.com>
Cc: "Jonathan Goldick" <jonathan.goldick@onstor.com>,
	"Jay Michlin" <jay.michlin@onstor.com>,
	"Brian DeForest" <brian.deforest@onstor.com>,
	"dl-Design Review" <dl-designreview@onstor.com>

This is a multi-part message in MIME format.

------_=_NextPart_001_01C75F5E.019FB362
Content-Type: text/plain;
	charset="us-ascii"
Content-Transfer-Encoding: quoted-printable

Ian,

=20

Thanks for your comments. Please see my responses below in blue.

=20

-Charissa

=20

________________________________

From: Ian Brown=20
Sent: Monday, March 05, 2007 10:56 AM
To: Charissa Willard
Cc: Jonathan Goldick; Jay Michlin; Brian DeForest; dl-Design Review
Subject: Re: CLI Refactoring Functional Spec

=20

I have an interview candidate today that will keep me from being at this
meeting for the whole time, however I have some comments, please bring
these up at the meeting.

=20

0, This looks good over all.

=20

1, The nfxsh should always return an error value if an error occurs, --
I mention this because the design doc should explicitly say this.
Currently some of the nfxsh commands will print an error and then the
return value from the shell will be successful -- this makes running
nfxsh commands from a shell script difficult.

[clw] I consider the fact that the cli code returned success when a
failure occurred to be a bug. We discussed that this was happening in
the cli code in one of our conference calls so we are aware of this
issue. Also, the DEFUN macro will be defined to return success or
failure the same way for all cli commands in addition to making sure
success is not returned when an error occurs.

=20

2, The "SSC" name is going away with cougar, so now would be a good time
to take it out of all the API names in the project.  Things like
"sscapi_status_t" should be changed to something like
"mgmtapi_status_t".

[clw} I wasn't aware that the "SSC" name was going away in Cougar. I'll
ask about this in the design review.

=20

3, All "printf"'s and the ilk (like "sprintf") should be replaced with
the bounded version of the call "snprintf", so there are no buffer
overflows.  This design document should specify that only the bounded
'n' versions of these APIs should be used.

[clw] Thanks. I'll look into incorporating "snprintf".

=20

4, The structure "sscapi_exception_t" is not defined in the
specification.  It needs to be design reviewed, so it needs to appear in
this design document.

[clw] sscapi_exception_t is defined in /ssc-api/ApiError.h (at least the
one I have.) It contains the app ID, error line number, error code, err
string, etc.

=20

5, This design document should include (in Section 9) the code for
testing the "cluster add nasgateway" command.  One thing that is
plaguing the software engineering process at ONStor is the lack of
regression testing -- this has been especially problematic with the CLI
and changes to it.  Due to the size/complexity of the ONStor product, it
is impossible to fully regress releases unless testing is automated.
Automated testing needs a design, and this is the proper document to
include that design in.  Every command and it's variations should have
automated tests. =20

            Since the new nfxsh is going to live on top of the a
management API, then it can be tested in it's own environment, with a
mock management API under it. =20

            All output should be tested, so that it is known when
someone changes the output of a command -- the current tests will fail.
This has been a constant problem, and even with this project, it will
not go away right away.

            Also included in the testing strategy, there should be tests
that specify exactly how many commands there are (i.e. count the number
of lines outputted by the "list" command), so that when an new command
is added, it is immediately known when running the nfxsh regression test
suite.

            I would be happy to help develop this test suite framework
and the tests for one of the commands (like the "cluster add
nasgateway") command, so that there are examples to follow when building
out the test suite.

            I'm not sure how to say this stronger, but the testing
strategy is very important with this project, and the long term cost
reduction of developing an automated test suite -- along side of
building each command in this new nfxsh/mgmtapi will be significant --
so much so that it is foolish to proceed with this project without
developing the test suite in parallel (or even prior) to the development
of this code.

=20

[clw] I totally agree with that there is indeed a huge testing effort
needed for this project. I also agree that we need to automate testing.
Not only because of this project, but because of the effect any cli
change has on other applications. Automated cli regression testing would
be a big benefit. In addition, because this project requires testing all
of the cli commands and possibly command option combinations, we are
already looking into what it would take to automate this task. We
discussed this issue in the last 2 conference calls I had with HCL. I'm
waiting for more information on this from them. I'll keep you in the
loop regarding this issue.=20

=20

Ian

=20

=20

On Feb 27, 2007, at 2:40 PM, Charissa Willard wrote:





<meeting.ics>

<CLI Refactoring - Functional Spec.doc>

=20


------_=_NextPart_001_01C75F5E.019FB362
Content-Type: text/html;
	charset="us-ascii"
Content-Transfer-Encoding: quoted-printable

<html xmlns:v=3D"urn:schemas-microsoft-com:vml" =
xmlns:o=3D"urn:schemas-microsoft-com:office:office" =
xmlns:w=3D"urn:schemas-microsoft-com:office:word" =
xmlns:st1=3D"urn:schemas-microsoft-com:office:smarttags" =
xmlns=3D"http://www.w3.org/TR/REC-html40">

<head>
<meta http-equiv=3DContent-Type content=3D"text/html; =
charset=3Dus-ascii">
<meta name=3DGenerator content=3D"Microsoft Word 11 (filtered medium)">
<!--[if !mso]>
<style>
v\:* {behavior:url(#default#VML);}
o\:* {behavior:url(#default#VML);}
w\:* {behavior:url(#default#VML);}
.shape {behavior:url(#default#VML);}
</style>
<![endif]--><o:SmartTagType
 namespaceuri=3D"urn:schemas-microsoft-com:office:smarttags" =
name=3D"PersonName"/>
<!--[if !mso]>
<style>
st1\:*{behavior:url(#default#ieooui) }
</style>
<![endif]-->
<style>
<!--
 /* Font Definitions */
 @font-face
	{font-family:Helvetica;
	panose-1:2 11 6 4 2 2 2 2 2 4;}
@font-face
	{font-family:Tahoma;
	panose-1:2 11 6 4 3 5 4 4 2 4;}
 /* Style Definitions */
 p.MsoNormal, li.MsoNormal, div.MsoNormal
	{margin:0in;
	margin-bottom:.0001pt;
	font-size:12.0pt;
	font-family:"Times New Roman";}
a:link, span.MsoHyperlink
	{color:blue;
	text-decoration:underline;}
a:visited, span.MsoHyperlinkFollowed
	{color:purple;
	text-decoration:underline;}
span.EmailStyle19
	{mso-style-type:personal-reply;
	font-family:"Courier New";
	color:windowtext;
	font-weight:normal;
	font-style:normal;
	text-decoration:none none;}
@page Section1
	{size:8.5in 11.0in;
	margin:1.0in 1.25in 1.0in 1.25in;}
div.Section1
	{page:Section1;}
-->
</style>

</head>

<body lang=3DEN-US link=3Dblue vlink=3Dpurple style=3D'word-wrap: =
break-word;
-khtml-nbsp-mode: space;-khtml-line-break: after-white-space'>

<div class=3DSection1>

<p class=3DMsoNormal><font size=3D1 face=3D"Courier New"><span =
style=3D'font-size:9.0pt;
font-family:"Courier New"'>Ian,<o:p></o:p></span></font></p>

<p class=3DMsoNormal><font size=3D1 face=3D"Courier New"><span =
style=3D'font-size:9.0pt;
font-family:"Courier New"'><o:p>&nbsp;</o:p></span></font></p>

<p class=3DMsoNormal><font size=3D1 face=3D"Courier New"><span =
style=3D'font-size:9.0pt;
font-family:"Courier New"'>Thanks for your comments. Please see my =
responses below
in <font color=3Dblue><span =
style=3D'color:blue'>blue</span></font>.<o:p></o:p></span></font></p>

<p class=3DMsoNormal><font size=3D1 face=3D"Courier New"><span =
style=3D'font-size:9.0pt;
font-family:"Courier New"'><o:p>&nbsp;</o:p></span></font></p>

<p class=3DMsoNormal><font size=3D1 face=3D"Courier New"><span =
style=3D'font-size:9.0pt;
font-family:"Courier New"'>-Charissa<o:p></o:p></span></font></p>

<p class=3DMsoNormal><font size=3D1 face=3D"Courier New"><span =
style=3D'font-size:9.0pt;
font-family:"Courier New"'><o:p>&nbsp;</o:p></span></font></p>

<div>

<div class=3DMsoNormal align=3Dcenter style=3D'text-align:center'><font =
size=3D3
face=3D"Times New Roman"><span style=3D'font-size:12.0pt'>

<hr size=3D2 width=3D"100%" align=3Dcenter tabindex=3D-1>

</span></font></div>

<p class=3DMsoNormal><b><font size=3D2 face=3DTahoma><span =
style=3D'font-size:10.0pt;
font-family:Tahoma;font-weight:bold'>From:</span></font></b><font =
size=3D2
face=3DTahoma><span style=3D'font-size:10.0pt;font-family:Tahoma'> =
<st1:PersonName
w:st=3D"on">Ian Brown</st1:PersonName> <br>
<b><span style=3D'font-weight:bold'>Sent:</span></b> Monday, March 05, =
2007 10:56
AM<br>
<b><span style=3D'font-weight:bold'>To:</span></b> <st1:PersonName =
w:st=3D"on">Charissa
 Willard</st1:PersonName><br>
<b><span style=3D'font-weight:bold'>Cc:</span></b> <st1:PersonName =
w:st=3D"on">Jonathan
 Goldick</st1:PersonName>; <st1:PersonName w:st=3D"on">Jay =
Michlin</st1:PersonName>;
<st1:PersonName w:st=3D"on">Brian DeForest</st1:PersonName>; dl-Design =
Review<br>
<b><span style=3D'font-weight:bold'>Subject:</span></b> Re: CLI =
Refactoring
Functional Spec</span></font><o:p></o:p></p>

</div>

<p class=3DMsoNormal><font size=3D3 face=3D"Times New Roman"><span =
style=3D'font-size:
12.0pt'><o:p>&nbsp;</o:p></span></font></p>

<p class=3DMsoNormal><font size=3D3 face=3D"Times New Roman"><span =
style=3D'font-size:
12.0pt'>I have an interview candidate today that will keep me from being =
at
this meeting for the whole time, however I have some comments, please =
bring
these up at the meeting.<o:p></o:p></span></font></p>

<div>

<div>

<p class=3DMsoNormal><font size=3D3 face=3D"Times New Roman"><span =
style=3D'font-size:
12.0pt'><o:p>&nbsp;</o:p></span></font></p>

</div>

<div>

<p class=3DMsoNormal><font size=3D3 face=3D"Times New Roman"><span =
style=3D'font-size:
12.0pt'>0, This looks good over all.<o:p></o:p></span></font></p>

</div>

<div>

<p class=3DMsoNormal><font size=3D3 face=3D"Times New Roman"><span =
style=3D'font-size:
12.0pt'><o:p>&nbsp;</o:p></span></font></p>

</div>

<div>

<p class=3DMsoNormal><font size=3D3 face=3D"Times New Roman"><span =
style=3D'font-size:
12.0pt'>1, The nfxsh should always return an error value if an error =
occurs, --
I mention this because the design doc should explicitly say this.&nbsp;
Currently some of the nfxsh commands will print an error and then the =
return
value from the shell will be successful -- this makes running nfxsh =
commands
from a shell script difficult.<o:p></o:p></span></font></p>

<p class=3DMsoNormal><font size=3D1 color=3Dblue face=3D"Courier =
New"><span
style=3D'font-size:9.0pt;font-family:"Courier New";color:blue'>[clw] I =
consider
the fact that the cli code returned success when a failure occurred to =
be a
bug. We discussed that this was happening in the cli code in one of our
conference calls so we are aware of this issue. Also, the DEFUN macro =
will be
defined to return success or failure the same way for all cli commands =
in
addition to making sure success is not returned when an error =
occurs.<o:p></o:p></span></font></p>

</div>

<div>

<p class=3DMsoNormal><font size=3D3 face=3D"Times New Roman"><span =
style=3D'font-size:
12.0pt'><o:p>&nbsp;</o:p></span></font></p>

</div>

<div>

<p class=3DMsoNormal><font size=3D3 face=3D"Times New Roman"><span =
style=3D'font-size:
12.0pt'>2, The &quot;SSC&quot; name is going away with cougar, so now =
would be
a good time to take it out of all the API names in the project.&nbsp; =
Things
like &quot;sscapi_status_t&quot; should be changed to something like
&quot;mgmtapi_status_t&quot;.<o:p></o:p></span></font></p>

<p class=3DMsoNormal><font size=3D1 color=3Dblue face=3D"Courier =
New"><span
style=3D'font-size:9.0pt;font-family:"Courier New";color:blue'>[clw} I =
wasn&#8217;t
aware that the &#8220;SSC&#8221; name was going away in Cougar. =
I&#8217;ll ask
about this in the design review.<o:p></o:p></span></font></p>

</div>

<div>

<p class=3DMsoNormal><font size=3D3 face=3D"Times New Roman"><span =
style=3D'font-size:
12.0pt'><o:p>&nbsp;</o:p></span></font></p>

</div>

<div>

<p class=3DMsoNormal><font size=3D3 face=3D"Times New Roman"><span =
style=3D'font-size:
12.0pt'>3, All &quot;printf&quot;'s and the ilk (like =
&quot;sprintf&quot;)
should be replaced with the bounded version of the call =
&quot;snprintf&quot;,
so there are no buffer overflows.&nbsp; This design document should =
specify
that only the bounded 'n' versions of these APIs should be =
used.<o:p></o:p></span></font></p>

<p class=3DMsoNormal><font size=3D1 color=3Dblue face=3D"Courier =
New"><span
style=3D'font-size:9.0pt;font-family:"Courier New";color:blue'>[clw] =
Thanks. I&#8217;ll
look into incorporating =
&#8220;snprintf&#8221;.<o:p></o:p></span></font></p>

</div>

<div>

<p class=3DMsoNormal><font size=3D3 face=3D"Times New Roman"><span =
style=3D'font-size:
12.0pt'><o:p>&nbsp;</o:p></span></font></p>

</div>

<div>

<p class=3DMsoNormal><font size=3D3 face=3D"Times New Roman"><span =
style=3D'font-size:
12.0pt'>4, The structure &quot;</span></font><span =
class=3Dapple-style-span><font
size=3D2 face=3D"Courier New"><span =
style=3D'font-size:10.0pt;font-family:"Courier =
New"'>sscapi_exception_t&quot;</span></font></span><span
class=3Dapple-style-span><font size=3D2 face=3DHelvetica><span =
style=3D'font-size:10.0pt;
font-family:Helvetica'>&nbsp;is not defined in the specification.&nbsp; =
It
needs to be design reviewed, so it needs to appear in this design =
document.<o:p></o:p></span></font></span></p>

<p class=3DMsoNormal><font size=3D1 color=3Dblue face=3D"Courier =
New"><span
style=3D'font-size:9.0pt;font-family:"Courier New";color:blue'>[clw] =
sscapi_exception_t
is defined in /ssc-api/ApiError.h (at least the one I have.) It contains =
the
app ID, error line number, error code, err string, =
etc.<o:p></o:p></span></font></p>

</div>

<div>

<p class=3DMsoNormal><font size=3D3 face=3D"Times New Roman"><span =
style=3D'font-size:
12.0pt'><o:p>&nbsp;</o:p></span></font></p>

</div>

<div>

<p class=3DMsoNormal><font size=3D3 face=3D"Times New Roman"><span =
style=3D'font-size:
12.0pt'>5, This design document should include (in Section 9) the code =
for
testing the &quot;cluster add nasgateway&quot; command.&nbsp; One thing =
that is
plaguing the software engineering process at ONStor is the lack of =
regression
testing -- this has been especially problematic with the CLI and changes =
to
it.&nbsp; Due to the size/complexity of the ONStor product, it is =
impossible to
fully regress releases unless testing is automated.&nbsp; Automated =
testing
needs a design, and this is the proper document to include that design
in.&nbsp; Every command and it's variations should have automated
tests.&nbsp;&nbsp;<o:p></o:p></span></font></p>

</div>

<div>

<p class=3DMsoNormal><span class=3Dapple-tab-span><font size=3D3
face=3D"Times New Roman"><span =
style=3D'font-size:12.0pt'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbs=
p;&nbsp;&nbsp;&nbsp; </span></font></span>Since
the new nfxsh is going to live on top of the a management API, then it =
can be
tested in it's own environment, with a mock management API under it. =
&nbsp;<o:p></o:p></p>

</div>

<div>

<p class=3DMsoNormal><span class=3Dapple-tab-span><font size=3D3
face=3D"Times New Roman"><span =
style=3D'font-size:12.0pt'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbs=
p;&nbsp;&nbsp;&nbsp; </span></font></span>All
output should be tested, so that it is known when someone changes the =
output of
a command -- the current tests will fail.&nbsp; This has been a constant
problem, and even with this project, it will not go away right =
away.<o:p></o:p></p>

</div>

<div>

<p class=3DMsoNormal><span class=3Dapple-tab-span><font size=3D3
face=3D"Times New Roman"><span =
style=3D'font-size:12.0pt'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbs=
p;&nbsp;&nbsp;&nbsp; </span></font></span>Also
included in the testing strategy, there should be tests that specify =
exactly
how many commands there are (i.e. count the number of lines outputted by =
the
&quot;list&quot; command), so that when an new command is added, it
is&nbsp;immediately known when running the nfxsh regression test =
suite.<o:p></o:p></p>

</div>

<div>

<p class=3DMsoNormal><span class=3Dapple-tab-span><font size=3D3
face=3D"Times New Roman"><span =
style=3D'font-size:12.0pt'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbs=
p;&nbsp;&nbsp;&nbsp; </span></font></span>I
would be happy to help develop this test suite framework and the tests =
for one
of the commands (like the &quot;cluster add nasgateway&quot;) command, =
so that
there are examples to follow when building out the test =
suite.<o:p></o:p></p>

</div>

<div>

<p class=3DMsoNormal><span class=3Dapple-tab-span><font size=3D3
face=3D"Times New Roman"><span =
style=3D'font-size:12.0pt'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbs=
p;&nbsp;&nbsp;&nbsp; </span></font></span>I'm
not sure how to say this stronger, but the testing strategy is very =
important
with this project, and the long term cost reduction of developing an =
automated
test suite -- along side of building each command in this new =
nfxsh/mgmtapi
will be significant -- so much so that it is foolish to proceed with =
this
project without developing the test suite in parallel (or even prior) to =
the
development of this code.<o:p></o:p></p>

<p class=3DMsoNormal><font size=3D1 face=3D"Courier New"><span =
style=3D'font-size:9.0pt;
font-family:"Courier New"'><o:p>&nbsp;</o:p></span></font></p>

<p class=3DMsoNormal><font size=3D1 color=3Dblue face=3D"Courier =
New"><span
style=3D'font-size:9.0pt;font-family:"Courier New";color:blue'>[clw] I =
totally
agree with that there is indeed a huge testing effort needed for this =
project. I
also agree that we need to automate testing. Not only because of this =
project,
but because of the effect any cli change has on other applications. =
Automated
cli regression testing would be a big benefit. In addition, because this
project requires testing all of the cli commands and possibly command =
option
combinations, we are already looking into what it would take to automate =
this
task. We discussed this issue in the last 2 conference calls I had with =
HCL. I&#8217;m
waiting for more information on this from them. I&#8217;ll keep you in =
the loop
regarding this issue. <o:p></o:p></span></font></p>

</div>

<div>

<p class=3DMsoNormal><font size=3D3 face=3D"Times New Roman"><span =
style=3D'font-size:
12.0pt'><o:p>&nbsp;</o:p></span></font></p>

</div>

<div>

<p class=3DMsoNormal><font size=3D3 face=3D"Times New Roman"><span =
style=3D'font-size:
12.0pt'>Ian<o:p></o:p></span></font></p>

</div>

<div>

<div>

<div>

<p class=3DMsoNormal><font size=3D3 face=3D"Times New Roman"><span =
style=3D'font-size:
12.0pt'><o:p>&nbsp;</o:p></span></font></p>

</div>

<div>

<p class=3DMsoNormal><font size=3D3 face=3D"Times New Roman"><span =
style=3D'font-size:
12.0pt'><o:p>&nbsp;</o:p></span></font></p>

</div>

<div>

<p class=3DMsoNormal><font size=3D3 face=3D"Times New Roman"><span =
style=3D'font-size:
12.0pt'>On Feb 27, 2007, at 2:40 PM, <st1:PersonName =
w:st=3D"on">Charissa Willard</st1:PersonName>
wrote:<o:p></o:p></span></font></p>

</div>

<p class=3DMsoNormal><font size=3D3 face=3D"Times New Roman"><span =
style=3D'font-size:
12.0pt'><br>
<br>
<o:p></o:p></span></font></p>

<div>

<p class=3DMsoNormal><font size=3D3 face=3D"Times New Roman"><span =
style=3D'font-size:
12.0pt'>&lt;meeting.ics&gt;<o:p></o:p></span></font></p>

</div>

<div>

<p class=3DMsoNormal><font size=3D3 face=3D"Times New Roman"><span =
style=3D'font-size:
12.0pt'>&lt;CLI Refactoring - Functional =
Spec.doc&gt;<o:p></o:p></span></font></p>

</div>

</div>

<p class=3DMsoNormal><font size=3D3 face=3D"Times New Roman"><span =
style=3D'font-size:
12.0pt'><o:p>&nbsp;</o:p></span></font></p>

</div>

</div>

</div>

</body>

</html>

------_=_NextPart_001_01C75F5E.019FB362--
