So, I'm wondering how much of this is unnecessarily splitting hairs on
what defines a cross-project spec.  If you look at the currently merged
specs, they are in fact both Guidelines:

Would renaming mine Eventlet Guidelines make it more palatable? :-)

I say that somewhat tongue in cheek, but the reality is that a lot of
the specs proposed to openstack-specs are basically the same thing:
prescriptive best practices to make our projects more
consistent/robust/usable.  Also, there's an implied action required for
each of them, which is to find any projects not following the guidelines
and assimilate them (resistance is futile! ;-).

Given that, I do question the value of creating yet another
cross-project repo that people will have to watch just to house
long-lived "specs" like these.  If anything, I would say that the more
limited timeframe specs should move into a cycle-specific folder like
they are in the other projects, although TBH the only ones I'm seeing
proposed so far that would meet that definition is the eventlet->[other
concurrency model] specs because if we decide to go forward with them
they will at some point be "done".  All of the others I see proposed
seem to be indefinite "here's how you should be doing $SOMETHING" documents.

Ultimately I guess I don't care where these things end up living as long
as they exist somewhere, but splitting this repo feels like extra
bureaucracy for no tangible benefit to me.  Ultimately I think I would
prefer a policies vs. cycles split in-repo like we have for Oslo over
creating another repo that will behave exactly the same way except for
the intended lifespan of the specs.

/2 cents


On 02/25/2015 01:54 PM, Doug Hellmann 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.
> 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] 
> [2]
> [3]
> [4] 
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe:

OpenStack Development Mailing List (not for usage questions)

Reply via email to