Open Stack

Hello,

I agree with the fact that flat specs structure would be really convenient
to manage the blueprints especially for different releases.

With the idea for seperate folder per repository/guide/book would make it
difficult to track cross repo/guide/book dependences. But we could use the
dependency section for the same, it should reflect on the web UI
(launchpad) irrespective of how we structure it on the back end. The
biggest hurdle for flat specs repo I could see is "too-many-blueprints". If
that is not going to be a problem, +1 for flat specs repo.

Regards,
Pranav


On Thu, Jun 26, 2014 at 2:03 AM, <openstack-docs-request at lists.openstack.org
> wrote:

> Send Openstack-docs mailing list submissions to
>         openstack-docs at lists.openstack.org
>
> To subscribe or unsubscribe via the World Wide Web, visit
>         http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
> or, via email, send a message with subject or body 'help' to
>         openstack-docs-request at lists.openstack.org
>
> You can reach the person managing the list at
>         openstack-docs-owner at lists.openstack.org
>
> When replying, please edit your Subject line so it is more specific
> than "Re: Contents of Openstack-docs digest..."
>
>
> Today's Topics:
>
>    1. Re: doc-specs repo? (Andreas Jaeger)
>    2. Re: doc-specs repo? (Sean Roberts)
>    3. Re: docs-specs repository (Sean Roberts)
>
>
> ----------------------------------------------------------------------
>
> Message: 1
> Date: Wed, 25 Jun 2014 21:55:35 +0200
> From: Andreas Jaeger <aj at suse.com>
> To: Anne Gentle <anne at openstack.org>,
>         "openstack-docs at lists.openstack.org"
>         <openstack-docs at lists.openstack.org>
> Subject: Re: [Openstack-docs] doc-specs repo?
> Message-ID: <53AB2937.5020507 at suse.com>
> Content-Type: text/plain; charset=ISO-8859-1
>
> On 06/25/2014 04:56 PM, Anne Gentle wrote:
> > Hi all,
> > I wanted to hear more from the teams about a need for a doc-specs repo.
> > The training team has started to bring specs into their repo. I'm happy
> > to get this started for the Documentation program but wanted to get some
> > input.
> >
> > I'd like to have an openstack/doc-spec repo set up with different
> > directories for each area of the documentation. Some projects have
> > designated by release as well, though since only our install guide and
> > config guides are "released" I think we could just have:
> > /api
> > /training
> > /user
> > /appdev
> > juno/ops (this is where install and config specs would live)
> > /security
>
> Some of this is not really clear. Why not just use the repository names
> like:
> api-site
> operations-guide
> manuals (or openstack-manuals)
> doc-tools (or openstack-doc-tools)
> security
> training-guides ?
>
> I'm fine with giving it a try for a release cycle,
> Andreas
> --
>  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
>   SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany
>    GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg)
>     GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126
>
>
>
> ------------------------------
>
> Message: 2
> Date: Wed, 25 Jun 2014 13:22:14 -0700
> From: Sean Roberts <seanrob at yahoo-inc.com>
> To: Andreas Jaeger <aj at suse.com>, Anne Gentle <anne at openstack.org>,
>         "openstack-docs at lists.openstack.org"
>         <openstack-docs at lists.openstack.org>
> Subject: Re: [Openstack-docs] doc-specs repo?
> Message-ID:
>         <1403727734.99165.YahooMailNeo at web125905.mail.ne1.yahoo.com>
> Content-Type: text/plain; charset="iso-8859-1"
>
> Having many sub-directories follows the docs layout because of the
> different repos. If we go that way then we would need to treat each project
> directory separate with their own release directories like?
> /doc-spec/training-guides/juno
>
> The drawback will be that this makes finding approved specs difficult. The
> other projects are using the single /specs directory with a flat naming
> scheme like ml2-dell-afc-mech-driver.rst.
>
> For specs that overlay projects like install-guides and training-guides,
> it will be confusing which, what, where. Because of this I vote for this
> structure
>
> doc-spec -
>         specs -
>                 juno - (all docs program juno cycle RST reside here)
>         tests -
>         doc -
> ?
>
>
> Sean Roberts
> Infrastructure Strategy, Yahoo
> seanrob at yahoo-inc.com
> (925) 980-4729
>
>
> On Wednesday, June 25, 2014 12:59 PM, Andreas Jaeger <aj at suse.com> wrote:
>
>
>
> On 06/25/2014 04:56 PM, Anne Gentle wrote:
> > Hi all,
> > I wanted to hear more from the teams about a need for a doc-specs repo.
> > The training team has started to bring specs into their repo. I'm happy
> > to get this started for the Documentation program but wanted to get some
> > input.
> >
> > I'd like to have an openstack/doc-spec repo set up with different
> > directories for each area of the documentation. Some projects have
> > designated by release as well, though since only our install guide and
> > config guides are "released" I think we could just have:
> > /api
> > /training
> > /user
> > /appdev
> > juno/ops (this is where install and config specs would live)
> > /security
>
> Some of this is not really clear. Why not just use the repository names
> like:
> api-site
> operations-guide
> manuals (or openstack-manuals)
> doc-tools (or openstack-doc-tools)
> security
> training-guides ?
>
> I'm fine with giving it a try for a release cycle,
> Andreas
> --
> Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
> ? SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany
> ?  GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg)
> ? ? GPG fingerprint = 93A3 365E CE47 B889 DF7F? FED1 389A 563C C272 A126
>
>
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
> -------------- next part --------------
> An HTML attachment was scrubbed...
> URL: <
> http://lists.openstack.org/pipermail/openstack-docs/attachments/20140625/362a2f69/attachment-0001.html
> >
>
> ------------------------------
>
> Message: 3
> Date: Wed, 25 Jun 2014 13:33:07 -0700
> From: Sean Roberts <seanrob at yahoo-inc.com>
> To: Sean Roberts <seanrob at yahoo-inc.com>, "openstack-docs >>
>         openstack-docs at lists.openstack.org"
>         <openstack-docs at lists.openstack.org>
> Subject: Re: [Openstack-docs] docs-specs repository
> Message-ID:
>         <1403728387.44565.YahooMailNeo at web125901.mail.ne1.yahoo.com>
> Content-Type: text/plain; charset="iso-8859-1"
>
> As a parallel thread to Anne's doc-specs repo, I propose that we start
> with the neutron spec template.rst and skeleton.rst found here?
> https://github.com/openstack/neutron-specs/tree/master/specs. We would
> remove the REST API impact, security, notifications, and performance impact
> sections. I would modify the Data Model Impact to doc/common docs Impact.
>
> Once we figure out the naming bits from the other thread and the template
> highlights here, then an Infra patch to create the repo would be the next
> step.
> ?
>
>
> Sean Roberts
> Infrastructure Strategy, Yahoo
> seanrob at yahoo-inc.com
> (925) 980-4729
> On Monday, June 23, 2014 10:11 PM, Sean Roberts <seanrob at yahoo-inc.com>
> wrote:
>
>
>
> The training-guides team has been seriously looking at using specs as a
> blueprint development step. After discussing the topic with Anne, we
> thought discussing having a program wide spec repo was a good idea.?
> So I propose the documentation program use the repo Openstack/docs-spec.
> We would still create a wiki page as the starting point. The design would
> follow an RST template, so important bits of information do not get missed.?
> Here are the steps the training guides project are considering. We were
> planning just a repo sub-directory, but that would change with the above
> plan.?
> Create a Blueprint
>         1. The blueprint is created here?
> https://blueprints.launchpad.net/openstack-training-guides/+addspec, only
> the name, title, and summary need to be filled out
>         2. Submit a spec RST patch based on the template?
> https://github.com/openstack/training-guides/blob/master/specs/template.rst
>         3. Gerrit reviews are the debate and refinement
>         4. Final RST patch either is rejected or approved
>         5. If the RST patch is approved, then it gets merged, the
> blueprint is approved, and the RST details are manually updated into the
> blueprint
>         6. The blueprint can only be approved for current release
>         7. Blueprints not approved or not implemented during a release
> cycle need the RST patch be resubmitted for the next cycle
> ~sean
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
> -------------- next part --------------
> An HTML attachment was scrubbed...
> URL: <
> http://lists.openstack.org/pipermail/openstack-docs/attachments/20140625/96f637f5/attachment.html
> >
>
> ------------------------------
>
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>
> End of Openstack-docs Digest, Vol 24, Issue 45
> **********************************************
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140630/4ec6e73e/attachment-0001.html>