Open Stack

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:
http://specs.openstack.org/openstack/openstack-specs/

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

-Ben

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] 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
>