Open Stack

Some questions below to help me see through your dev lens.

> 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).

These are an excellent place where coders can highlight additions and
changes. Would love to see this required on patches for all projects -
make it a habit.

>
>
>
> 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.
>
>

Fantastic.

>
> 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.
>

Mentioned this in my doc report this week, not sure if mindfulness
will be a result of docs or the other way around, either way,
migration information is needed. I think it's good to have in the dev
docs, but really, migration is an ops task, yes?

>
> 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.
>

Not sure if a project-by-project approach to installation is helpful
for all projects, but a use-case-by-use-case discussion of
installation would be good to include with dev docs. Ideally you'd all
contribute to "the" install/deploy guide in openstack-manuals. Let's
deep dive into this:
cinder - never install it on its own
nova - never install it on its own
swift - has a "swift-all-in-one" install doc, though it probably
should include keystone
horizon - never install it on its own
glance - never install it on its own
keystone - never install it on its own
(new) ceilometer -never install it on its own

To install for development work, devs use devstack or anvil, right?
Are my assumptions correct here or am I not looking through your dev
lens?

Thanks for these suggestions and discussion.

Anne

>
> 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.
>
>
>
> Knowing what the changes were for a given release (ie a 'changelog' file)
> Possibly a 'migration' file that would explain how to migrate from version
> N-1
> 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
>