Open Stack

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).




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