Open Stack

Excerpts from Ben Nemec's message of 2015-02-27 09:25:37 -0800:
> On 02/27/2015 03:54 AM, Thierry Carrez wrote:
> > Doug Hellmann wrote:
> >> Maybe some of the folks in the meeting who felt more strongly that it
> >> should be a separate document can respond with their thoughts?
> > 
> > I don't feel very strongly and could survive this landing in
> > openstack-specs. My objection was the following:
> > 
> > - Specs are for designing the solution and implementation plan to a
> > specific problem. They are mainly used by developers and reviewers
> > during implementation as a clear reference rationale for change and
> > approved plan. Once they are fully implemented, they are kept for
> > history purpose, not for constant reference.
> > 
> > - Guidelines/developer doc are for all developers (old and new) to
> > converge on best practices on topics that are not directly implemented
> > as hacking rules. They are constantly used by everyone (not just
> > developers/reviewers of a given feature) and never become "history".
> > 
> > Putting guidelines doc in the middle of specs makes it a bit less
> > discoverable imho, especially by our new developers. It's harder to
> > determine which are still current and you should read. An "OpenStack
> > developer doc" sounds like a much better entry point.
> > 
> > That said, the devil is in the details, and some efforts start as specs
> > (for existing code to catch up with the recommendation) and become
> > guidelines (for future code being written). That is the case of the log
> > levels spec: it is both a spec and a guideline. Personally I wouldn't
> > object if that was posted in both areas, or if the relevant pieces were
> > copied, once the current code has caught up, from the spec to a dev
> > guideline.
> > 
> > In the eventlet case, it's only a set of best practices / guidelines:
> > there is no specific problem to solve, no catch-up plan for existing
> > code to implement. Only a collection of recommendations if you get to
> > write future eventlet-based code. Those won't start or end. Which is why
> > I think it should go straight to a developer doc.
> > 
> 
> Well, this whole spec arose because we found out there was existing code
> that was doing bad things with eventlet monkey patching that needed to
> be fixed.  The specific problem is actually being worked concurrently
> with the spec because everyone involved has agreed on a solution, which
> became one of the guidelines in the spec.  I'd be surprised if there
> aren't other projects that need similar changes to be in line with the
> new recommendations though.  I'd hope that future projects will follow
> the guidelines, but they were actually written for the purpose of
> eliminating as many potential eventlet gotchas in our _current_ code as
> possible.  Coming up with a specific list of changes needed is tough
> until we have agreement on the best practices though, which is why the
> first work item is a somewhat vague "audit and fix all the things" point.
> 
> Personally, I would expect most best practice/guideline type specs to be
> similar.  Nobody's going to take the time to write up a spec about
> something everyone's already doing - they're going to do it because one
> or a few projects have found something that works well and they think
> everyone should be doing it.  So I think your point about most of these
> things moving from spec to guideline throughout their lifetime is spot
> on, I'm just wondering if it's worth complicating the workflow for that
> process.  Herding the cats for something big like the log guidelines is
> hard enough without requiring two separate documents for the immediate
> work and the long-term information.
> 
> That said, I agree with the points about publishing this stuff under a
> developer reference doc rather than specs, and if that can't be done in
> a single repo maybe we do have to split.  I'd still prefer to keep it
> all in one repo though - moving a doc between directories is a lot
> simpler than moving it between repos (and also doesn't lose any previous
> discussion in Gerrit).
> 

There are numerous wiki pages that have a wealth of knowledge, but
very poor history attached. Such as:

  * https://wiki.openstack.org/wiki/Python3
  * https://wiki.openstack.org/wiki/GitCommitMessages
  * https://wiki.openstack.org/wiki/Gerrit_Workflow
  * https://wiki.openstack.org/wiki/Getting_The_Code
  * https://wiki.openstack.org/wiki/Testr

Just having these in git would be useful, and having the full change
history with the same care given to commit messages and with reviewers
would I think improve the content and usability of these.

Since these are not even close to "specs", but make excellent static
documents, I think having them in a cross-project developer
documentation repository makes a lot of sense.

That said, I do think that we would need to have a much lower bar for
reviews (maybe just 1 * +2, but let it sit at least 3 days or something
to allow for exposure).

I'd be quite happy to help with an effort to convert the wiki pages
above into rst and move forward with things like the eventlet guides.