[openstack-dev] [all] creating a unified developer reference manual

Doug Hellmann doug at doughellmann.com
Thu Feb 26 21:12:41 UTC 2015



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-request at 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-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev



More information about the OpenStack-dev mailing list