Open Stack

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).

-Ben