<font face="Default Sans Serif,Verdana,Arial,Helvetica,sans-serif" size="2"><div>+1<br><br>Cheers,<br><br>Christopher Ferris<br>IBM Distinguished Engineer, CTO Industry and Cloud Standards<br>Member, IBM Academy of Technology<br>IBM Software Group, Standards Strategy<br>email: chrisfer@us.ibm.com<br>Twitter: christo4ferris<br>phone: +1 508 234 2986</div><br><br><font color="#990099">-----Gabriel Hurley <Gabriel.Hurley@nebula.com> wrote: -----</font><div style="padding-left:5px;"><div style="padding-right:0px;padding-left:5px;border-left:solid black 2px;">To: OpenStack Development Mailing List <openstack-dev@lists.openstack.org><br>From: Gabriel Hurley <Gabriel.Hurley@nebula.com><br>Date: 08/31/2012 01:51PM<br>Subject: Re: [openstack-dev] Question on component docs<br><br> <!--Notes ACF <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">--> <!--[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]--> <div class="WordSection1"> <p class="MsoNormal"><span style="font-size: 11pt; font-family: Calibri, sans-serif; "><font color="#1f497d">+1 on making sure every project *<b>has</b>* these pieces; standardizing them is less of a priority in my mind.<o:p></o:p></font></span></p> <p class="MsoNormal"><span style="font-size: 11pt; font-family: Calibri, sans-serif; "><font color="#1f497d"><o:p> </o:p></font></span></p> <p class="MsoNormal"><span style="font-size: 11pt; font-family: Calibri, sans-serif; "><font color="#1f497d">Personally, I prefer very thorough release notes published with the documentation (a la http://docs.openstack.org/developer/horizon/#release-notes ), as it  gives a more thorough overview than just a changelog. In those release notes I like to highlight 3 key areas:<o:p></o:p></font></span></p> <p class="MsoListParagraph" style="margin-left:27.0pt;text-indent:-.25in;mso-list:l0 level1 lfo2"> <!--[if !supportLists]--><span style="font-size: 11pt; font-family: Symbol; "><font color="#1f497d"><span style="mso-list:Ignore">·<span style="font:7.0pt "Times New Roman"">         </span></span></font></span><!--[endif]--><span style="font-size: 11pt; font-family: Calibri, sans-serif; "><font color="#1f497d">release highlights (features and fixes)<o:p></o:p></font></span></p> <p class="MsoListParagraph" style="margin-left:27.0pt;text-indent:-.25in;mso-list:l0 level1 lfo2"> <!--[if !supportLists]--><span style="font-size: 11pt; font-family: Symbol; "><font color="#1f497d"><span style="mso-list:Ignore">·<span style="font:7.0pt "Times New Roman"">         </span></span></font></span><!--[endif]--><span style="font-size: 11pt; font-family: Calibri, sans-serif; "><font color="#1f497d">known issues<o:p></o:p></font></span></p> <p class="MsoListParagraph" style="margin-left:27.0pt;text-indent:-.25in;mso-list:l0 level1 lfo2"> <!--[if !supportLists]--><span style="font-size: 11pt; font-family: Symbol; "><font color="#1f497d"><span style="mso-list:Ignore">·<span style="font:7.0pt "Times New Roman"">         </span></span></font></span><!--[endif]--><span style="font-size: 11pt; font-family: Calibri, sans-serif; "><font color="#1f497d">backwards-incompatible changes (if there are any).<o:p></o:p></font></span></p> <p class="MsoNormal"><span style="font-size: 11pt; font-family: Calibri, sans-serif; "><font color="#1f497d"><o:p> </o:p></font></span></p> <p class="MsoNormal"><span style="font-size: 11pt; font-family: Calibri, sans-serif; "><font color="#1f497d">Covering those three areas makes sure people upgrading really know what they’re getting. I’m already working on the Folsom release notes for Horizon.<o:p></o:p></font></span></p> <p class="MsoNormal"><span style="font-size: 11pt; font-family: Calibri, sans-serif; "><font color="#1f497d"><o:p> </o:p></font></span></p> <p class="MsoNormal"><span style="font-size: 11pt; font-family: Calibri, sans-serif; "><font color="#1f497d">I do like the idea of having a migration guide published for each version, though. I think that’d be helpful in making people mindful of what backwards-incompatible  changes they’ve made in a release cycle.<o:p></o:p></font></span></p> <p class="MsoNormal"><span style="font-size: 11pt; font-family: Calibri, sans-serif; "><font color="#1f497d"><o:p> </o:p></font></span></p> <p class="MsoNormal"><span style="font-size: 11pt; font-family: Calibri, sans-serif; "><font color="#1f497d">Though many (if not all) of the projects do have some form of installation guide already they could all be better. The problem there is that there are so many  ways to install/setup/configure that writing a single guide is impractical. I think it’s better to have a concise summary of installation/deployment concerns that people should be made aware of, and then to provide sort of a “sample” or “reference” installation  guide as a companion to that documentation.<o:p></o:p></font></span></p> <p class="MsoNormal"><span style="font-size: 11pt; font-family: Calibri, sans-serif; "><font color="#1f497d"><o:p> </o:p></font></span></p> <p class="MsoNormal"><span style="font-size: 11pt; font-family: Calibri, sans-serif; "><font color="#1f497d">Great suggestions!<o:p></o:p></font></span></p> <p class="MsoNormal"><span style="font-size: 11pt; font-family: Calibri, sans-serif; "><font color="#1f497d"><o:p> </o:p></font></span></p> <p class="MsoListParagraph" style="margin-left:27.0pt;text-indent:-.25in;mso-list:l2 level1 lfo3"> <!--[if !supportLists]--><span style="font-size: 11pt; font-family: Calibri, sans-serif; "><font color="#1f497d"><span style="mso-list:Ignore">-<span style="font:7.0pt "Times New Roman"">          </span></span></font></span><!--[endif]--><span style="font-size: 11pt; font-family: Calibri, sans-serif; "><font color="#1f497d">Gabriel<o:p></o:p></font></span></p> <p class="MsoNormal"><span style="font-size: 11pt; font-family: Calibri, sans-serif; "><font color="#1f497d"><o:p> </o:p></font></span></p> <div style="border:none;border-left:solid blue 1.5pt;padding:0in 0in 0in 4.0pt"> <div> <div style="border:none;border-top:solid #B5C4DF 1.0pt;padding:3.0pt 0in 0in 0in"> <p class="MsoNormal"><b><span style="font-size:10.0pt;font-family:"Tahoma","sans-serif"">From:</span></b><span style="font-size:10.0pt;font-family:"Tahoma","sans-serif""> Joshua Harlow [mailto:harlowja@yahoo-inc.com] <br> <b>Sent:</b> Friday, August 31, 2012 10:26 AM<br> <b>To:</b> OpenStack Development Mailing List<br> <b>Subject:</b> [openstack-dev] Question on component docs<o:p></o:p></span></p> </div> </div> <p class="MsoNormal"><o:p> </o:p></p> <div> <p class="MsoNormal"><span style="font-size:10.5pt;font-family:"Calibri","sans-serif";color:black">Hi all,<o:p></o:p></span></p> </div> <div> <p class="MsoNormal"><span style="font-size:10.5pt;font-family:"Calibri","sans-serif";color:black"><o:p> </o:p></span></p> </div> <div> <p class="MsoNormal"><span style="font-size:10.5pt;font-family:"Calibri","sans-serif";color:black">I was wondering if we could figure out a way to standardize on each project having a set of docs in certain locations that would be used for the following. <o:p></o:p></span></p> </div> <div> <p class="MsoNormal"><span style="font-size:10.5pt;font-family:"Calibri","sans-serif";color:black"><o:p> </o:p></span></p> </div> <ol start="1" type="1"> <li class="MsoNormal" style="color:black;mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;mso-list:l1 level1 lfo1"> <span style="font-size:10.5pt;font-family:"Calibri","sans-serif"">Knowing what the changes were for a given release (ie a 'changelog' file)<o:p></o:p></span></li><li class="MsoNormal" style="color:black;mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;mso-list:l1 level1 lfo1"> <span style="font-size:10.5pt;font-family:"Calibri","sans-serif"">Possibly a 'migration' file that would explain how to migrate from version N-1<o:p></o:p></span></li><li class="MsoNormal" style="color:black;mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;mso-list:l1 level1 lfo1"> <span style="font-size:10.5pt;font-family:"Calibri","sans-serif"">Docs on how to install/setup/configure for the current code (kept up to date locally, not in devstack…)<o:p></o:p></span></li></ol> <div> <p class="MsoNormal"><span style="font-size:10.5pt;font-family:"Calibri","sans-serif";color:black">Right now it seems like some of these are in rst (for docs.openstack.org), some are in devstack/rst (the nitty gritty about how to install), some are nonexistent  (ie the changelog?). It would seem like each project should have the same set of files in the same locations for all 3 of these without having to refer to X other projects (devstack, the docs pages…).<o:p></o:p></span></p> </div> <div> <p class="MsoNormal"><span style="font-size:10.5pt;font-family:"Calibri","sans-serif";color:black"><o:p> </o:p></span></p> </div> <div> <p class="MsoNormal"><span style="font-size:10.5pt;font-family:"Calibri","sans-serif";color:black">What do people think?<o:p></o:p></span></p> </div> <div> <p class="MsoNormal"><span style="font-size:10.5pt;font-family:"Calibri","sans-serif";color:black">Is something like this feasible, desired (it'd be nice for me to not have to look at devstack to know how stuff is installed)?<o:p></o:p></span></p> </div> <div> <p class="MsoNormal"><span style="font-size:10.5pt;font-family:"Calibri","sans-serif";color:black">Thoughts?<o:p></o:p></span></p> </div> <div> <p class="MsoNormal"><span style="font-size:10.5pt;font-family:"Calibri","sans-serif";color:black"><o:p> </o:p></span></p> </div> <div> <p class="MsoNormal"><span style="font-size:10.5pt;font-family:"Calibri","sans-serif";color:black">-Josh<o:p></o:p></span></p> </div> <div> <p class="MsoNormal"><span style="font-size:10.5pt;font-family:"Calibri","sans-serif";color:black"><o:p> </o:p></span></p> </div> </div> </div> <div><font face="Courier New,Courier,monospace" size="3">_______________________________________________<br>OpenStack-dev mailing list<br>OpenStack-dev@lists.openstack.org<br><a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br></font></div></div></div></font>