Open Stack

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.

-- 
Thierry Carrez (ttx)