On Wed, Feb 25, 2015 at 12:49 PM, Doug Hellmann <d...@doughellmann.com> wrote:
> > > 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. > 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. > > 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 >
__________________________________________________________________________ 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