On Thu, Feb 26, 2015, at 03:55 PM, Ben Nemec wrote: > 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/
That's a fair point. I was inclined to go ahead and use the existing specs repo, but I said I would start the discussion on the mailing list. Maybe some of the folks in the meeting who felt more strongly that it should be a separate document can respond with their thoughts? Doug > > 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-requ...@lists.openstack.org?subject:unsubscribe > > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > > > > > __________________________________________________________________________ > OpenStack Development Mailing List (not for usage questions) > Unsubscribe: > openstack-dev-requ...@lists.openstack.org?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
