<div>+1 - These should be required for OpenStack core projects</div><div><br></div><div>-Blake</div><div><br></div>On Fri, Aug 31, 2012 at 12:47 PM, Gabriel Hurley <span dir="ltr"><<a href="mailto:Gabriel.Hurley@nebula.com" target="_blank">Gabriel.Hurley@nebula.com</a>></span> wrote:<br>
<div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div lang="EN-US" link="blue" vlink="purple">
<div>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1f497d">+1 on making sure every project *<b>has</b>* these pieces; standardizing them is less of a priority in my mind.<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1f497d"><u></u> <u></u></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1f497d">Personally, I prefer very thorough release notes published with the documentation (a la <a href="http://docs.openstack.org/developer/horizon/#release-notes" target="_blank">http://docs.openstack.org/developer/horizon/#release-notes</a> ), as it
gives a more thorough overview than just a changelog. In those release notes I like to highlight 3 key areas:<u></u><u></u></span></p>
<p style="margin-left:27.0pt">
<u></u><span style="font-size:11.0pt;font-family:Symbol;color:#1f497d"><span>·<span style="font:7.0pt "Times New Roman"">
</span></span></span><u></u><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1f497d">release highlights (features and fixes)<u></u><u></u></span></p>
<p style="margin-left:27.0pt">
<u></u><span style="font-size:11.0pt;font-family:Symbol;color:#1f497d"><span>·<span style="font:7.0pt "Times New Roman"">
</span></span></span><u></u><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1f497d">known issues<u></u><u></u></span></p>
<p style="margin-left:27.0pt">
<u></u><span style="font-size:11.0pt;font-family:Symbol;color:#1f497d"><span>·<span style="font:7.0pt "Times New Roman"">
</span></span></span><u></u><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1f497d">backwards-incompatible changes (if there are any).<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1f497d"><u></u> <u></u></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";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.<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1f497d"><u></u> <u></u></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";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.<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1f497d"><u></u> <u></u></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";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.<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1f497d"><u></u> <u></u></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1f497d">Great suggestions!<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1f497d"><u></u> <u></u></span></p>
<p style="margin-left:27.0pt">
<u></u><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1f497d"><span>-<span style="font:7.0pt "Times New Roman"">
</span></span></span><u></u><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1f497d">Gabriel<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1f497d"><u></u> <u></u></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:<a href="mailto:harlowja@yahoo-inc.com" target="_blank">harlowja@yahoo-inc.com</a>]
<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<u></u><u></u></span></p>
</div>
</div><div><div class="h5">
<p class="MsoNormal"><u></u> <u></u></p>
<div>
<p class="MsoNormal"><span style="font-size:10.5pt;font-family:"Calibri","sans-serif"">Hi all,<u></u><u></u></span></p>
</div>
<div>
<p class="MsoNormal"><span style="font-size:10.5pt;font-family:"Calibri","sans-serif""><u></u> <u></u></span></p>
</div>
<div>
<p class="MsoNormal"><span style="font-size:10.5pt;font-family:"Calibri","sans-serif"">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. <u></u><u></u></span></p>
</div>
<div>
<p class="MsoNormal"><span style="font-size:10.5pt;font-family:"Calibri","sans-serif""><u></u> <u></u></span></p>
</div>
<ol start="1" type="1">
<li class="MsoNormal" style>
<span style="font-size:10.5pt;font-family:"Calibri","sans-serif"">Knowing what the changes were for a given release (ie a 'changelog' file)<u></u><u></u></span></li><li class="MsoNormal" style>
<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<u></u><u></u></span></li><li class="MsoNormal" style>
<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…)<u></u><u></u></span></li></ol>
<div>
<p class="MsoNormal"><span style="font-size:10.5pt;font-family:"Calibri","sans-serif"">Right now it seems like some of these are in rst (for <a href="http://docs.openstack.org" target="_blank">docs.openstack.org</a>), 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…).<u></u><u></u></span></p>
</div>
<div>
<p class="MsoNormal"><span style="font-size:10.5pt;font-family:"Calibri","sans-serif""><u></u> <u></u></span></p>
</div>
<div>
<p class="MsoNormal"><span style="font-size:10.5pt;font-family:"Calibri","sans-serif"">What do people think?<u></u><u></u></span></p>
</div>
<div>
<p class="MsoNormal"><span style="font-size:10.5pt;font-family:"Calibri","sans-serif"">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)?<u></u><u></u></span></p>
</div>
<div>
<p class="MsoNormal"><span style="font-size:10.5pt;font-family:"Calibri","sans-serif"">Thoughts?<u></u><u></u></span></p>
</div>
<div>
<p class="MsoNormal"><span style="font-size:10.5pt;font-family:"Calibri","sans-serif""><u></u> <u></u></span></p>
</div>
<div>
<p class="MsoNormal"><span style="font-size:10.5pt;font-family:"Calibri","sans-serif"">-Josh<u></u><u></u></span></p>
</div>
<div>
<p class="MsoNormal"><span style="font-size:10.5pt;font-family:"Calibri","sans-serif""><u></u> <u></u></span></p>
</div>
</div></div></div>
</div>
</div>
<br>_______________________________________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><br>
<a 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>