<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Wed, Feb 25, 2015 at 12:49 PM, Doug Hellmann <span dir="ltr"><<a href="mailto:doug@doughellmann.com" target="_blank">doug@doughellmann.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="HOEnZb"><div class="h5"><br>
<br>
On Wed, Feb 25, 2015, at 03:14 PM, Joe Gordon wrote:<br>
> On Wed, Feb 25, 2015 at 11:54 AM, Doug Hellmann <<a href="mailto:doug@doughellmann.com">doug@doughellmann.com</a>><br>
> wrote:<br>
><br>
> > During yesterday’s cross-project meeting [1], we discussed the "Eventlet<br>
> > Best Practices” spec [2] started by bnemec. The discussion of that spec<br>
> > revolved around the question of whether our cross-project specs repository<br>
> > is the right place for this type of document that isn’t a “plan” for a<br>
> > change, and is more a reference guide. Eventually we came around to the<br>
> > idea of creating a cross-project developer guide to hold these sorts of<br>
> > materials.<br>
> ><br>
> > That leads to two questions, then:<br>
> ><br>
> > 1. Should we have a unified developer guide for the project?<br>
> > 2. Where should it live and how should we manage it?<br>
> ><br>
> > I believe we would benefit by having a more formal place to write down<br>
> > some of our experiences in ways that make them discoverable. We have been<br>
> > using the wiki for this, but it is often challenging to find information in<br>
> > the wiki if you don’t generally know where to look for it. That leads to an<br>
> > answer to question 2: create a new git repository to host a Sphinx-based<br>
> > manual similar to what many projects already have. We would then try to<br>
> > unify content from all sources where it applies to the whole project, and<br>
> > we could eventually start moving some of the wiki content into it as well.<br>
> ><br>
> > Oslo has already started moving some of our reference materials from the<br>
> > wiki into a “policy” section of the oslo-specs repository, and one benefit<br>
> > we found to using git to manage those policy documents is that we have a<br>
> > record of the discussion of the changes to the pages, and we can<br>
> > collaborate on changes through our code review system — so everyone on the<br>
> > team has a voice and can comment on the changes. It can also be a bit<br>
> > easier to do things like include sample code [3].<br>
> ><br>
> > Right now each project has its own reference guide, with project-specific<br>
> > information in it. Not all projects are going to agree to all of the<br>
> > guidelines, but it will be useful to have the conversation about those<br>
> > points where we are doing things differently so we can learn from each<br>
> > other.<br>
> ><br>
><br>
> I like the idea of a unified developer reference. There is a bunch of<br>
> stuff<br>
> in the nova devref that isn't nova specific such as:<br>
><br>
> <a href="http://docs.openstack.org/developer/nova/devref/unit_tests.html" target="_blank">http://docs.openstack.org/developer/nova/devref/unit_tests.html</a><br>
><br>
> As for how to manage what is project specific and what isn't.  Something<br>
> along the lines of how we do it in hacking may be nice. Each project has<br>
> its own file that has project specific things and references the main<br>
> hacking doc<br>
> (<a href="https://github.com/openstack/keystone/blob/master/HACKING.rst" target="_blank">https://github.com/openstack/keystone/blob/master/HACKING.rst</a>).<br>
<br>
</div></div>I was more interested in how we come to agree on what is global vs. what<br>
isn't, but I definitely agree that anything deemed project-specific<br>
should stay in the project's documentation somewhere.<br></blockquote><div><br></div><div>As you know, doing this in Hacking has been difficult.  So I don't have any good answers here, except I think there is a ton of low hanging fruit that we can tackle first.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<span class="HOEnZb"><font color="#888888"><br>
Doug<br>
</font></span><div class="HOEnZb"><div class="h5"><br>
><br>
><br>
><br>
><br>
> ><br>
> > If we decide to create the repository, we would also need to decide how it<br>
> > would be managed. The rules set up for the cross-project specs repository<br>
> > seems close to what we want (everyone can +1/-1; TC members can +2/-2; the<br>
> > TC chair tallies the votes and uses workflow+1) [4].<br>
> ><br>
> > An alternative is to designate a subsection of the openstack-specs<br>
> > repository for the content, as we’ve done in Oslo. In this case, though, I<br>
> > think it makes more sense to create a new repository. If there is a general<br>
> > agreement to go ahead with the plan, I will set that up with a Sphinx<br>
> > project framework to get us started.<br>
> ><br>
> > Comments?<br>
> ><br>
> > Doug<br>
> ><br>
> ><br>
> > [1]<br>
> > <a href="http://eavesdrop.openstack.org/meetings/crossproject/2015/crossproject.2015-02-24-21.03.log.html" target="_blank">http://eavesdrop.openstack.org/meetings/crossproject/2015/crossproject.2015-02-24-21.03.log.html</a><br>
> > [2] <a href="https://review.openstack.org/#/c/154642/" target="_blank">https://review.openstack.org/#/c/154642/</a><br>
> > [3] <a href="http://docs.openstack.org/developer/oslo.log/api/fixtures.html" target="_blank">http://docs.openstack.org/developer/oslo.log/api/fixtures.html</a><br>
> > [4]<br>
> > <a href="http://eavesdrop.openstack.org/meetings/tc/2015/tc.2015-02-24-20.02.log.html" target="_blank">http://eavesdrop.openstack.org/meetings/tc/2015/tc.2015-02-24-20.02.log.html</a><br>
> > __________________________________________________________________________<br>
> > OpenStack Development Mailing List (not for usage questions)<br>
> > Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" target="_blank">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br>
> > <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
> ><br>
> __________________________________________________________________________<br>
> OpenStack Development Mailing List (not for usage questions)<br>
> Unsubscribe:<br>
> <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" target="_blank">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br>
> <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
<br>
__________________________________________________________________________<br>
OpenStack Development Mailing List (not for usage questions)<br>
Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" target="_blank">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
</div></div></blockquote></div><br></div></div>