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.



[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

Reply via email to