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: [email protected]?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: [email protected]?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
