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