Open Stack

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.

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