Open Stack

On Wed, Feb 25, 2015, at 03:14 PM, Joe Gordon wrote:
> On Wed, Feb 25, 2015 at 11:54 AM, Doug Hellmann <doug at 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-request at 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-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev