[Openstack-docs] Linking to external install guides
Tom Fifield
tom at openstack.org
Thu Jul 11 03:26:45 UTC 2013
On 11/07/13 01:43, Anne Gentle wrote:
>
>
>
> On Wed, Jul 10, 2013 at 10:21 AM, Steve Gordon <sgordon at redhat.com
> <mailto:sgordon at redhat.com>> wrote:
>
> ----- Original Message -----
> > From: "Lorin Hochstein" <lorin at nimbisservices.com
> <mailto:lorin at nimbisservices.com>>
> > To: "Steve Gordon" <sgordon at redhat.com <mailto:sgordon at redhat.com>>
> > Cc: "Tom Fifield" <tom at openstack.org <mailto:tom at openstack.org>>,
> openstack-docs at lists.openstack.org
> <mailto:openstack-docs at lists.openstack.org>
> > Sent: Wednesday, July 10, 2013 9:04:26 AM
> > Subject: Re: [Openstack-docs] Linking to external install guides
> >
> > This definitely falls under the scope of the documentation
> effort. Alas, we
> > still don't even have the folsom->grizzly process fully
> documented yet <
> > https://bugs.launchpad.net/openstack-manuals/+bug/1087483>.
>
> Yeah, my non-documentation concern is that improvement in this area
> requires some improved focus on identifying upgrade issues *before*
> release from the programs actually delivering the code. This is my
> interpretation just by following along the Folsom->Grizzly bug and
> attempting such an upgrade myself.
>
>
> What has happened in the past is Razique would upgrade in production,
> keeping good notes, then bring them in to the documentation.
>
> Razique documented cactus to diablo and diablo to essex:
> https://review.openstack.org/#/c/18053/3 in December 2012.
>
> Alvaro Garcia did essex to folsom in
> https://review.openstack.org/#/c/21657/ in Feb 2013.
>
> Razique's still assigned to folsom to grizzly.
> https://bugs.launchpad.net/openstack-manuals/+bug/1087483
>
> He may have decent notes and just hasn't put them in a patch yet so
> check with him.
>
>
> > I added a new bug for documenting grizzly->havana <
> > https://bugs.launchpad.net/openstack-manuals/+bug/1199773>.
>
> Thanks, I have started adding some more specific thoughts about the
> process there. A more general question is where in the documentation
> suite would we expect that content to live?
>
>
> Usually it goes in the Install Guide, just the timing is after the release.
You'll get no argument from me about this - it's a bit of an embarrasing
thing right now that upgrades are so hard :)
We have some generic information here:
http://docs.openstack.org/trunk/openstack-ops/content/maintenance.html#upgrades
and I have some more stuff to steal from NeCTAR who are doing their
Folsom->Grizzly upgrade today after a couple of months of prep.
>
>
>
> > On Wed, Jul 10, 2013 at 8:43 AM, Steve Gordon <sgordon at redhat.com
> <mailto:sgordon at redhat.com>> wrote:
> >
> > > ----- Original Message -----
> > > > From: "Tom Fifield" <tom at openstack.org
> <mailto:tom at openstack.org>>
> > > > To: openstack-docs at lists.openstack.org
> <mailto:openstack-docs at lists.openstack.org>
> > > > Sent: Tuesday, July 9, 2013 8:34:25 PM
> > > > Subject: Re: [Openstack-docs] Linking to external install guides
> > > >
> > > > On 10/07/13 00:48, Steve Gordon wrote:
> > > > > ----- Original Message -----
> > > > >> From: "Lorin Hochstein" <lorin at nimbisservices.com
> <mailto:lorin at nimbisservices.com>>
> > > > >> To: "Steve Gordon" <sgordon at redhat.com
> <mailto:sgordon at redhat.com>>
> > > > >> Cc: "Anne Gentle" <annegentle at justwriteclick.com
> <mailto:annegentle at justwriteclick.com>>,
> > > > >> openstack-docs at lists.openstack.org
> <mailto:openstack-docs at lists.openstack.org>
> > > > >> Sent: Tuesday, July 9, 2013 10:38:26 AM
> > > > >> Subject: Re: [Openstack-docs] Linking to external install
> guides
> > > > >>
> > > > >> On Mon, Jul 8, 2013 at 3:36 PM, Steve Gordon
> <sgordon at redhat.com <mailto:sgordon at redhat.com>>
> > > wrote:
> > > > >>
> > > > >>> ----- Original Message -----
> > > > >>>> From: "Anne Gentle" <annegentle at justwriteclick.com
> <mailto:annegentle at justwriteclick.com>>
> > > > >>>> To: "Lorin Hochstein" <lorin at nimbisservices.com
> <mailto:lorin at nimbisservices.com>>
> > > > >>>> Cc: openstack-docs at lists.openstack.org
> <mailto:openstack-docs at lists.openstack.org>
> > > > >>>> Sent: Monday, July 8, 2013 11:03:05 AM
> > > > >>>> Subject: Re: [Openstack-docs] Linking to external
> install guides
> > > > >>>>
> > > > >>>> So, for the last few releases, I would update
> > > > >>>> http://www.openstack.org/software/start/ with links to the
> > > downstream
> > > > >>>> deployment documentation. It was natural at the time.
> > > > >>>>
> > > > >>>> What has changed as of last week is that documentation
> is now an
> > > > >>>> official
> > > > >>>> "Program" and we'll need to propose the goals for the
> documentation
> > > and
> > > > >>>> make a scope for release docs. To me, this change means
> we should be
> > > > >>>> more
> > > > >>>> tight and targeted with our install docs as they'll be
> part of the
> > > > >>>> integrated release.
> > > > >>>
> > > > >>> Downstream deployment materials tend to cover arguably more
> > > streamlined
> > > > >>> approaches to deployment, such as Foreman, PackStack,
> Ansible, JuJu,
> > > etc.
> > > > >>> The flip side however is these deployment methods are not
> considered
> > > part
> > > > >>> of OpenStack itself and may not in fact be ready to
> deploy a new
> > > release
> > > > >>> on
> > > > >>> day dot. These approaches also don't necessarily have 1:1
> equivalents
> > > > >>> across distributions.
> > > > >>>
> > > > >>> For these reasons my feeling is the documentation
> "program" should be
> > > > >>> concentrated on delivering accurate manual installation
> steps at
> > > release
> > > > >>> time in a consolidated installation guide as suggested in the
> > > restructure
> > > > >>> blueprint [1]. I don't think however this precludes also
> linking the
> > > > >>> distribution specific materials somewhere as they become
> available,
> > > it
> > > > >>> just
> > > > >>> wouldn't be a blocker to the integrated release?
> > > > >>>
> > > > >>> -Steve
> > > > >>>
> > > > >>> [1]
> > > https://wiki.openstack.org/wiki/Blueprint-restructure-documentation
> > > > >>>
> > > > >>
> > > > >>
> > > > >> At the last design summit, we talked about the doc team no
> longer
> > > > >> maintaining any install documentation at all going
> forward, leaving
> > > that
> > > > >> entirely to downstream projects. I really do think that's
> the way we
> > > > >> should
> > > > >> go. I'm hesitant to maintain docs on a fully manual
> install (i.e.,
> > > from
> > > > >> source tarballs), since we really don't want people to do
> that.
> > > > >
> > > > > Yes, I realize now I should have clarified that by "manual"
> I still
> > > meant
> > > > > using packages - just without aids like those listed in my
> previous
> > > mail.
> > > > > I think trying to create and maintain documentation of from
> source
> > > > > installation that would potentially be even harder than
> this, despite
> > > the
> > > > > (potential) issues with packaged builds lagging behind the
> source
> > > release.
> > > > >
> > > > >> It means that documentation on how to do an install won't
> exist until
> > > the
> > > > >> downstream projects write these up, but since we recommend
> installing
> > > from
> > > > >> downstream packages, I think that's unavoidable. Since
> we're seeing a
> > > lot
> > > > >> more support for OpenStack downstream these days, I think
> those
> > > projects
> > > > >> have more of an incentive to get their packages and docs
> ready ASAP
> > > after
> > > > >> a
> > > > >> release.
> > > > >
> > > > > My understanding is that at least RPM/DEB packages are
> likely to be
> > > > > available *very* shortly after the actual release for Havana.
> > > >
> > > > I'll take a bullish line, which may not necessarily be
> achievable:
> > > >
> > > > """
> > > > On the day that the press release for Havana is sent out, we
> need -by
> > > > hook or by crook!- to have installation instructions for RHEL and
> > > > Ubuntu, and ideally SUSE and Debian too.
> > > > """
> > > >
> > > > I'm thinking: "if you can't install the software, then it's
> not really a
> > > > release, is it?". Release day is our time to shine :)
> > >
> > > Well, another huge gap that I think exists here is if you can't
> upgrade
> > > from the previous release it's not really a release. Currently
> I think this
> > > is a huge problem regardless of installation method because the
> only
> > > documentation available for upgrades appears to be some
> per-project notes
> > > in the release notes Wiki page. A bit tangential perhaps and
> not sure this
> > > is really just a documentation problem but thought I would
> bring it up.
> > >
> > > > So, feasibility/sanity check:
> > > > * This is unlikely to be provided in time by our friends at RH or
> > > > Canonical, leaving:
> > > > Option 1: Delay the press release
> > > > Option 2: DIY
> > > >
> > > > Personally, I think Option 1 would be terrible for the
> community's
> > > > "feelings", and tying OpenStack to particular product
> offerings is not
> > > > something we should probably be doing :)
> > >
> > > I've sent a query regarding build schedules for RDO on rdo-list
> [1]. No
> > > doubt there is package tweaking to be done but nightlies are
> already being
> > > built from trunk:
> > >
> > > http://repos.fedorapeople.org/repos/openstack/openstack-trunk/
> > >
> > > Thanks,
> > >
> > > Steve
> > >
> > > [1]
> https://www.redhat.com/archives/rdo-list/2013-July/msg00057.html
> > >
> > > _______________________________________________
> > > Openstack-docs mailing list
> > > Openstack-docs at lists.openstack.org
> <mailto:Openstack-docs at lists.openstack.org>
> > > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
> > >
> >
> >
> >
> > --
> > Lorin Hochstein
> > Lead Architect - Cloud Services
> > Nimbis Services, Inc.
> > www.nimbisservices.com <http://www.nimbisservices.com>
> >
>
> --
> Steve Gordon, RHCE
> Documentation Lead, Red Hat OpenStack
> Engineering Content Services
> Red Hat Canada (Toronto, Ontario)
>
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> <mailto:Openstack-docs at lists.openstack.org>
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>
>
>
> --
> Anne Gentle
> annegentle at justwriteclick.com <mailto:annegentle at justwriteclick.com>
>
>
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
More information about the Openstack-docs
mailing list