<div dir="ltr"><div>Hello,<br><br></div><div>I agree with the fact that flat specs structure would be really convenient to manage the blueprints especially for different releases.<br><br></div><div>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.<br>
</div><div><br></div>Regards,<br>Pranav<br><div class="gmail_extra"><br><br><div class="gmail_quote">On Thu, Jun 26, 2014 at 2:03 AM, <span dir="ltr"><<a href="mailto:openstack-docs-request@lists.openstack.org" target="_blank">openstack-docs-request@lists.openstack.org</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Send Openstack-docs mailing list submissions to<br>
<a href="mailto:openstack-docs@lists.openstack.org">openstack-docs@lists.openstack.org</a><br>
<br>
To subscribe or unsubscribe via the World Wide Web, visit<br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
or, via email, send a message with subject or body 'help' to<br>
<a href="mailto:openstack-docs-request@lists.openstack.org">openstack-docs-request@lists.openstack.org</a><br>
<br>
You can reach the person managing the list at<br>
<a href="mailto:openstack-docs-owner@lists.openstack.org">openstack-docs-owner@lists.openstack.org</a><br>
<br>
When replying, please edit your Subject line so it is more specific<br>
than "Re: Contents of Openstack-docs digest..."<br>
<br>
<br>
Today's Topics:<br>
<br>
1. Re: doc-specs repo? (Andreas Jaeger)<br>
2. Re: doc-specs repo? (Sean Roberts)<br>
3. Re: docs-specs repository (Sean Roberts)<br>
<br>
<br>
----------------------------------------------------------------------<br>
<br>
Message: 1<br>
Date: Wed, 25 Jun 2014 21:55:35 +0200<br>
From: Andreas Jaeger <<a href="mailto:aj@suse.com">aj@suse.com</a>><br>
To: Anne Gentle <<a href="mailto:anne@openstack.org">anne@openstack.org</a>>,<br>
"<a href="mailto:openstack-docs@lists.openstack.org">openstack-docs@lists.openstack.org</a>"<br>
<<a href="mailto:openstack-docs@lists.openstack.org">openstack-docs@lists.openstack.org</a>><br>
Subject: Re: [Openstack-docs] doc-specs repo?<br>
Message-ID: <<a href="mailto:53AB2937.5020507@suse.com">53AB2937.5020507@suse.com</a>><br>
Content-Type: text/plain; charset=ISO-8859-1<br>
<br>
On 06/25/2014 04:56 PM, Anne Gentle wrote:<br>
> Hi all,<br>
> I wanted to hear more from the teams about a need for a doc-specs repo.<br>
> The training team has started to bring specs into their repo. I'm happy<br>
> to get this started for the Documentation program but wanted to get some<br>
> input.<br>
><br>
> I'd like to have an openstack/doc-spec repo set up with different<br>
> directories for each area of the documentation. Some projects have<br>
> designated by release as well, though since only our install guide and<br>
> config guides are "released" I think we could just have:<br>
> /api<br>
> /training<br>
> /user<br>
> /appdev<br>
> juno/ops (this is where install and config specs would live)<br>
> /security<br>
<br>
Some of this is not really clear. Why not just use the repository names<br>
like:<br>
api-site<br>
operations-guide<br>
manuals (or openstack-manuals)<br>
doc-tools (or openstack-doc-tools)<br>
security<br>
training-guides ?<br>
<br>
I'm fine with giving it a try for a release cycle,<br>
Andreas<br>
--<br>
Andreas Jaeger aj@{<a href="http://suse.com" target="_blank">suse.com</a>,<a href="http://opensuse.org" target="_blank">opensuse.org</a>} Twitter/Identica: jaegerandi<br>
SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany<br>
GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg)<br>
GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126<br>
<br>
<br>
<br>
------------------------------<br>
<br>
Message: 2<br>
Date: Wed, 25 Jun 2014 13:22:14 -0700<br>
From: Sean Roberts <<a href="mailto:seanrob@yahoo-inc.com">seanrob@yahoo-inc.com</a>><br>
To: Andreas Jaeger <<a href="mailto:aj@suse.com">aj@suse.com</a>>, Anne Gentle <<a href="mailto:anne@openstack.org">anne@openstack.org</a>>,<br>
"<a href="mailto:openstack-docs@lists.openstack.org">openstack-docs@lists.openstack.org</a>"<br>
<<a href="mailto:openstack-docs@lists.openstack.org">openstack-docs@lists.openstack.org</a>><br>
Subject: Re: [Openstack-docs] doc-specs repo?<br>
Message-ID:<br>
<<a href="mailto:1403727734.99165.YahooMailNeo@web125905.mail.ne1.yahoo.com">1403727734.99165.YahooMailNeo@web125905.mail.ne1.yahoo.com</a>><br>
Content-Type: text/plain; charset="iso-8859-1"<br>
<br>
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?<br>
/doc-spec/training-guides/juno<br>
<br>
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.<br>
<br>
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<br>
<br>
doc-spec -<br>
specs -<br>
juno - (all docs program juno cycle RST reside here)<br>
tests -<br>
doc -<br>
?<br>
<br>
<br>
Sean Roberts<br>
Infrastructure Strategy, Yahoo<br>
<a href="mailto:seanrob@yahoo-inc.com">seanrob@yahoo-inc.com</a><br>
(925) 980-4729<br>
<br>
<br>
On Wednesday, June 25, 2014 12:59 PM, Andreas Jaeger <<a href="mailto:aj@suse.com">aj@suse.com</a>> wrote:<br>
<br>
<br>
<br>
On 06/25/2014 04:56 PM, Anne Gentle wrote:<br>
> Hi all,<br>
> I wanted to hear more from the teams about a need for a doc-specs repo.<br>
> The training team has started to bring specs into their repo. I'm happy<br>
> to get this started for the Documentation program but wanted to get some<br>
> input.<br>
><br>
> I'd like to have an openstack/doc-spec repo set up with different<br>
> directories for each area of the documentation. Some projects have<br>
> designated by release as well, though since only our install guide and<br>
> config guides are "released" I think we could just have:<br>
> /api<br>
> /training<br>
> /user<br>
> /appdev<br>
> juno/ops (this is where install and config specs would live)<br>
> /security<br>
<br>
Some of this is not really clear. Why not just use the repository names<br>
like:<br>
api-site<br>
operations-guide<br>
manuals (or openstack-manuals)<br>
doc-tools (or openstack-doc-tools)<br>
security<br>
training-guides ?<br>
<br>
I'm fine with giving it a try for a release cycle,<br>
Andreas<br>
--<br>
Andreas Jaeger aj@{<a href="http://suse.com" target="_blank">suse.com</a>,<a href="http://opensuse.org" target="_blank">opensuse.org</a>} Twitter/Identica: jaegerandi<br>
? SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 N?rnberg, Germany<br>
? GF: Jeff Hawn,Jennifer Guild,Felix Imend?rffer,HRB16746 (AG N?rnberg)<br>
? ? GPG fingerprint = 93A3 365E CE47 B889 DF7F? FED1 389A 563C C272 A126<br>
<br>
<br>
_______________________________________________<br>
Openstack-docs mailing list<br>
<a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
-------------- next part --------------<br>
An HTML attachment was scrubbed...<br>
URL: <<a href="http://lists.openstack.org/pipermail/openstack-docs/attachments/20140625/362a2f69/attachment-0001.html" target="_blank">http://lists.openstack.org/pipermail/openstack-docs/attachments/20140625/362a2f69/attachment-0001.html</a>><br>
<br>
------------------------------<br>
<br>
Message: 3<br>
Date: Wed, 25 Jun 2014 13:33:07 -0700<br>
From: Sean Roberts <<a href="mailto:seanrob@yahoo-inc.com">seanrob@yahoo-inc.com</a>><br>
To: Sean Roberts <<a href="mailto:seanrob@yahoo-inc.com">seanrob@yahoo-inc.com</a>>, "openstack-docs >><br>
<a href="mailto:openstack-docs@lists.openstack.org">openstack-docs@lists.openstack.org</a>"<br>
<<a href="mailto:openstack-docs@lists.openstack.org">openstack-docs@lists.openstack.org</a>><br>
Subject: Re: [Openstack-docs] docs-specs repository<br>
Message-ID:<br>
<<a href="mailto:1403728387.44565.YahooMailNeo@web125901.mail.ne1.yahoo.com">1403728387.44565.YahooMailNeo@web125901.mail.ne1.yahoo.com</a>><br>
Content-Type: text/plain; charset="iso-8859-1"<br>
<br>
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?<a href="https://github.com/openstack/neutron-specs/tree/master/specs" target="_blank">https://github.com/openstack/neutron-specs/tree/master/specs</a>. 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.<br>
<br>
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.<br>
?<br>
<br>
<br>
Sean Roberts<br>
Infrastructure Strategy, Yahoo<br>
<a href="mailto:seanrob@yahoo-inc.com">seanrob@yahoo-inc.com</a><br>
(925) 980-4729<br>
On Monday, June 23, 2014 10:11 PM, Sean Roberts <<a href="mailto:seanrob@yahoo-inc.com">seanrob@yahoo-inc.com</a>> wrote:<br>
<br>
<br>
<br>
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.?<br>
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.?<br>
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.?<br>
Create a Blueprint<br>
1. The blueprint is created here?<a href="https://blueprints.launchpad.net/openstack-training-guides/+addspec" target="_blank">https://blueprints.launchpad.net/openstack-training-guides/+addspec</a>, only the name, title, and summary need to be filled out<br>
2. Submit a spec RST patch based on the template?<a href="https://github.com/openstack/training-guides/blob/master/specs/template.rst" target="_blank">https://github.com/openstack/training-guides/blob/master/specs/template.rst</a><br>
3. Gerrit reviews are the debate and refinement<br>
4. Final RST patch either is rejected or approved<br>
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<br>
6. The blueprint can only be approved for current release<br>
7. Blueprints not approved or not implemented during a release cycle need the RST patch be resubmitted for the next cycle<br>
~sean<br>
_______________________________________________<br>
Openstack-docs mailing list<br>
<a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
-------------- next part --------------<br>
An HTML attachment was scrubbed...<br>
URL: <<a href="http://lists.openstack.org/pipermail/openstack-docs/attachments/20140625/96f637f5/attachment.html" target="_blank">http://lists.openstack.org/pipermail/openstack-docs/attachments/20140625/96f637f5/attachment.html</a>><br>
<br>
------------------------------<br>
<br>
_______________________________________________<br>
Openstack-docs mailing list<br>
<a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
<br>
<br>
End of Openstack-docs Digest, Vol 24, Issue 45<br>
**********************************************<br>
</blockquote></div><br></div></div>