<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Generator" content="Microsoft Word 15 (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]--><style><!--
/* Font Definitions */
@font-face
{font-family:"Cambria Math";
panose-1:2 4 5 3 5 4 6 3 2 4;}
@font-face
{font-family:Calibri;
panose-1:2 15 5 2 2 2 4 3 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0cm;
margin-bottom:.0001pt;
font-size:11.0pt;
font-family:"Calibri",sans-serif;}
a:link, span.MsoHyperlink
{mso-style-priority:99;
color:blue;
text-decoration:underline;}
a:visited, span.MsoHyperlinkFollowed
{mso-style-priority:99;
color:purple;
text-decoration:underline;}
p
{mso-style-priority:99;
margin:0cm;
margin-bottom:.0001pt;
font-size:12.0pt;
font-family:"Times New Roman",serif;}
p.MsoListParagraph, li.MsoListParagraph, div.MsoListParagraph
{mso-style-priority:34;
margin-top:0cm;
margin-right:0cm;
margin-bottom:0cm;
margin-left:36.0pt;
margin-bottom:.0001pt;
font-size:11.0pt;
font-family:"Calibri",sans-serif;}
span.emailstyle17
{mso-style-name:emailstyle17;
font-family:"Calibri",sans-serif;
color:#1F497D;}
span.EmailStyle20
{mso-style-type:personal;
font-family:"Calibri",sans-serif;
color:windowtext;}
span.EmailStyle21
{mso-style-type:personal-reply;
font-family:"Calibri",sans-serif;
color:#1F497D;}
.MsoChpDefault
{mso-style-type:export-only;
font-size:10.0pt;}
@page WordSection1
{size:595.0pt 842.0pt;
margin:72.0pt 72.0pt 72.0pt 72.0pt;}
div.WordSection1
{page:WordSection1;}
--></style><!--[if gte mso 9]><xml>
<o:shapedefaults v:ext="edit" spidmax="1026" />
</xml><![endif]--><!--[if gte mso 9]><xml>
<o:shapelayout v:ext="edit">
<o:idmap v:ext="edit" data="1" />
</o:shapelayout></xml><![endif]-->
</head>
<body bgcolor="white" lang="EN-US" link="blue" vlink="purple">
<div class="WordSection1">
<p class="MsoNormal"><span style="color:#1F497D">The canonical place for the help/documentation must be the online documentation. We must provide information in the docs first, additional content should be added to the CLI help. The labels field contains arbitrary
metadata which can be consumed and used by the COE/bay, it has no set structure of format. Having an exhaustive list of possible metadata values should not be an aim of the command line help. Prior art in this area includes glance image properties[1] in which
the CLI provides no reference to the values that can be passed, nova scheduler hints[2] which also provides no information on the values that can be passed.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="color:#1F497D">There is a middle ground we should be treading. Users should not be using the CLI as a referencing for working out what label keys and values should be passed in to elicit a certain response from the bay, that
should found in the docs. I am in favor of adding a short list of commonly used labels to the CLI help to jog the memory of the user.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="color:#1F497D">I’m all for an additional man page which lists labels documentation, however this change is specifically about CLI “ --help”.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="color:#1F497D">[1] https://github.com/openstack/python-glanceclient/blob/master/glanceclient/v1/shell.py#L218<o:p></o:p></span></p>
<p class="MsoNormal"><span style="color:#1F497D">[2] https://github.com/openstack/python-novaclient/blob/master/novaclient/v2/shell.py#L526
<o:p></o:p></span></p>
<p class="MsoNormal"><span style="color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="color:#1F497D">Tom<o:p></o:p></span></p>
<p class="MsoNormal"><span style="color:#1F497D"><o:p> </o:p></span></p>
<div>
<div style="border:none;border-top:solid #E1E1E1 1.0pt;padding:3.0pt 0cm 0cm 0cm">
<p class="MsoNormal"><b>From:</b> Tim Bell [mailto:Tim.Bell@cern.ch] <br>
<b>Sent:</b> 12 May 2016 17:58<br>
<b>To:</b> OpenStack Development Mailing List (not for usage questions)<br>
<b>Cc:</b> Qun XK Wang<br>
<b>Subject:</b> Re: [openstack-dev] [magnum] How to document 'labels'<o:p></o:p></p>
</div>
</div>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">I’d be in favor of 1. <o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">At the end of the man page or full help text, a URL could be useful for more information but since most people using the CLI will have to do a context change to access the docs, it is not a simple click but a copy/paste/find the browser
window which is not so friendly.<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">Tim <o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<div style="border:none;border-top:solid #B5C4DF 1.0pt;padding:3.0pt 0cm 0cm 0cm">
<p class="MsoNormal"><b><span style="color:black">From: </span></b><span style="color:black">Jamie Hannaford <<a href="mailto:jamie.hannaford@rackspace.com">jamie.hannaford@rackspace.com</a>><br>
<b>Reply-To: </b>"OpenStack Development Mailing List (not for usage questions)" <<a href="mailto:openstack-dev@lists.openstack.org">openstack-dev@lists.openstack.org</a>><br>
<b>Date: </b>Thursday 12 May 2016 at 16:04<br>
<b>To: </b>"OpenStack Development Mailing List (not for usage questions)" <<a href="mailto:openstack-dev@lists.openstack.org">openstack-dev@lists.openstack.org</a>><br>
<b>Cc: </b>Qun XK Wang <<a href="mailto:bjwqun@cn.ibm.com">bjwqun@cn.ibm.com</a>><br>
<b>Subject: </b>Re: [openstack-dev] [magnum] How to document 'labels'</span><span style="font-size:12.0pt;color:black"><o:p></o:p></span></p>
</div>
<div>
<p class="MsoNormal"><span style="font-family:"Times New Roman",serif"><o:p> </o:p></span></p>
</div>
<blockquote style="border:none;border-left:solid #B5C4DF 4.5pt;padding:0cm 0cm 0cm 4.0pt;margin-left:3.75pt;margin-top:5.0pt;margin-right:0cm;margin-bottom:5.0pt" id="MAC_OUTLOOK_ATTRIBUTION_BLOCKQUOTE">
<div>
<div>
<p style="background:white"><span style="font-family:"Calibri",sans-serif;color:black">+1 for 1 and 3. <o:p></o:p></span></p>
<p style="background:white"><span style="font-family:"Calibri",sans-serif;color:black"><o:p> </o:p></span></p>
<p style="background:white"><span style="font-family:"Calibri",sans-serif;color:black">I'm not sure maintainability should discourage us from exposing information to the user through the client - we'll face the same maintenance burden as we currently do, and
IMO it's our job as a team to ensure our docs are up-to-date. Any kind of input which touches the API should also live in the API docs, because that's in line with every other OpenStack service.<o:p></o:p></span></p>
<p style="background:white"><span style="font-family:"Calibri",sans-serif;color:black"><o:p> </o:p></span></p>
<p style="background:white"><span style="font-family:"Calibri",sans-serif;color:black">I don't think I've seen documentation exposed via the API before (#2). I think it's a lot of work too, and I don't see what benefit it provides.<o:p></o:p></span></p>
<p style="background:white"><span style="font-family:"Calibri",sans-serif;color:black"><o:p> </o:p></span></p>
<p style="background:white"><span style="font-family:"Calibri",sans-serif;color:black">Jamie<o:p></o:p></span></p>
<p style="background:white"><span style="font-family:"Calibri",sans-serif;color:black"><o:p> </o:p></span></p>
<div>
<div class="MsoNormal" align="center" style="text-align:center;background:white">
<span style="font-size:12.0pt;color:#212121">
<hr size="2" width="98%" align="center">
</span></div>
<div id="divRplyFwdMsg">
<p class="MsoNormal" style="background:white"><b><span style="color:black">From:</span></b><span style="color:black"> Hongbin Lu <<a href="mailto:hongbin.lu@huawei.com">hongbin.lu@huawei.com</a>><br>
<b>Sent:</b> 11 May 2016 21:52<br>
<b>To:</b> OpenStack Development Mailing List (not for usage questions)<br>
<b>Cc:</b> Qun XK Wang<br>
<b>Subject:</b> [openstack-dev] [magnum] How to document 'labels'</span><span style="font-size:12.0pt;color:#212121">
<o:p></o:p></span></p>
<div>
<p class="MsoNormal" style="background:white"><span style="font-size:12.0pt;color:#212121"> <o:p></o:p></span></p>
</div>
</div>
<div>
<div>
<p class="MsoNormal" style="background:white"><span style="color:#1F497D">Hi all,</span><span style="color:#212121"><o:p></o:p></span></p>
<p class="MsoNormal" style="background:white"><span style="color:#1F497D"> </span><span style="color:#212121"><o:p></o:p></span></p>
<p class="MsoNormal" style="background:white"><span style="color:#1F497D">This is a continued discussion from the last team meeting. For recap, ‘labels’ is a property in baymodel and is used by users to input additional key-pair pairs to configure the bay.
In the last team meeting, we discussed what is the best way to document ‘labels’. In general, I heard three options:</span><span style="color:#212121"><o:p></o:p></span></p>
<p class="MsoListParagraph" style="text-indent:-18.0pt;background:white"><span style="color:#1F497D">1.</span><span style="font-size:7.0pt;font-family:"Times New Roman",serif;color:#1F497D">
</span><span style="color:#1F497D">Place the documentation in Magnum CLI as help text (as Wangqun proposed [1][2]).</span><span style="color:#212121"><o:p></o:p></span></p>
<p class="MsoListParagraph" style="text-indent:-18.0pt;background:white"><span style="color:#1F497D">2.</span><span style="font-size:7.0pt;font-family:"Times New Roman",serif;color:#1F497D">
</span><span style="color:#1F497D">Place the documentation in Magnum server and expose them via the REST API. Then, have the CLI to load help text of individual properties from Magnum server.</span><span style="color:#212121"><o:p></o:p></span></p>
<p class="MsoListParagraph" style="text-indent:-18.0pt;background:white"><span style="color:#1F497D">3.</span><span style="font-size:7.0pt;font-family:"Times New Roman",serif;color:#1F497D">
</span><span style="color:#1F497D">Place the documentation in a documentation server (like developer.openstack.org/…), and add the doc link to the CLI help text.</span><span style="color:#212121"><o:p></o:p></span></p>
<p class="MsoNormal" style="background:white"><span style="color:#1F497D">For option #1, I think an advantage is that it is close to end-users, thus providing a better user experience. In contrast, Tom Cammann pointed out a disadvantage that the CLI help text
might be easier to become out of date. For option #2, it should work but incurs a lot of extra work. For option #3, the disadvantage is the user experience (since user need to click the link to see the documents) but it makes us easier to maintain. I am thinking
if it is possible to have a combination of #1 and #3. Thoughts?</span><span style="color:#212121"><o:p></o:p></span></p>
<p class="MsoNormal" style="background:white"><span style="color:#1F497D"> </span><span style="color:#212121"><o:p></o:p></span></p>
<p class="MsoNormal" style="background:white"><span style="color:#1F497D">[1] <a href="https://review.openstack.org/#/c/307631/">
https://review.openstack.org/#/c/307631/</a></span><span style="color:#212121"><o:p></o:p></span></p>
<p class="MsoNormal" style="background:white"><span style="color:#1F497D">[2] <a href="https://review.openstack.org/#/c/307642/">
https://review.openstack.org/#/c/307642/</a></span><span style="color:#212121"><o:p></o:p></span></p>
<p class="MsoNormal" style="background:white"><span style="color:#1F497D"> </span><span style="color:#212121"><o:p></o:p></span></p>
<p class="MsoNormal" style="background:white"><span style="color:#1F497D">Best regards,</span><span style="color:#212121"><o:p></o:p></span></p>
<p class="MsoNormal" style="background:white"><span style="color:#1F497D">Hongbin</span><span style="color:#212121"><o:p></o:p></span></p>
</div>
</div>
</div>
<p class="MsoNormal" style="background:white"><span style="font-size:12.0pt;color:black">
<o:p></o:p></span></p>
<div class="MsoNormal" align="center" style="text-align:center;background:white">
<span style="font-size:12.0pt;color:black">
<hr size="2" width="100%" align="center">
</span></div>
<p class="MsoNormal" style="background:white"><span style="font-size:12.0pt;color:black">Rackspace International GmbH a company registered in the Canton of Zurich, Switzerland (company identification number CH-020.4.047.077-1) whose registered office is at
Pfingstweidstrasse 60, 8005 Zurich, Switzerland. Rackspace International GmbH privacy policy can be viewed at
<a href="http://www.rackspace.co.uk/legal/swiss-privacy-policy">www.rackspace.co.uk/legal/swiss-privacy-policy</a> - This e-mail message may contain confidential or privileged information intended for the recipient. Any dissemination, distribution or copying
of the enclosed material is prohibited. If you receive this transmission in error, please notify us immediately by e-mail at
<a href="mailto:abuse@rackspace.com">abuse@rackspace.com</a> and delete the original message. Your cooperation is appreciated.
<o:p></o:p></span></p>
</div>
</div>
</blockquote>
</div>
</body>
</html>