Open Stack

On Wed, Feb 25, 2015 at 12:49 PM, Doug Hellmann <doug at 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 <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.
>

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-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
>
> __________________________________________________________________________
> 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20150225/46474c22/attachment.html>