Open Stack

+1 - These should be required for OpenStack core projects

-Blake

On Fri, Aug 31, 2012 at 12:47 PM, Gabriel Hurley
<Gabriel.Hurley at nebula.com>wrote:

>  +1 on making sure every project **has** these pieces; standardizing them
> is less of a priority in my mind.****
>
> ** **
>
> 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:****
>
> **·         **release highlights (features and fixes)****
>
> **·         **known issues****
>
> **·         **backwards-incompatible changes (if there are any).****
>
> ** **
>
> 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.****
>
> ** **
>
> 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.****
>
> ** **
>
> 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.****
>
> ** **
>
> Great suggestions!****
>
> ** **
>
> **-          **Gabriel****
>
> ** **
>
> *From:* Joshua Harlow [mailto:harlowja at yahoo-inc.com]
> *Sent:* Friday, August 31, 2012 10:26 AM
> *To:* OpenStack Development Mailing List
> *Subject:* [openstack-dev] Question on component docs****
>
> ** **
>
> Hi all,****
>
> ** **
>
> 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. ****
>
> ** **
>
>    1. Knowing what the changes were for a given release (ie a 'changelog'
>    file)****
>    2. Possibly a 'migration' file that would explain how to migrate from
>    version N-1****
>    3. Docs on how to install/setup/configure for the current code (kept
>    up to date locally, not in devstack…)****
>
>  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…).****
>
> ** **
>
> What do people think?****
>
> 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)?****
>
> Thoughts?****
>
> ** **
>
> -Josh****
>
> ** **
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20120831/bda737b1/attachment.html>