[openstack-dev] [cross-project] What are specifications?

Thierry Carrez thierry at openstack.org
Wed Mar 23 11:12:52 UTC 2016

Mike Perez wrote:
> [...]
> A proposal I would like to make:
> * Clarify what cross-project specifications are [5].
>    - I do think specifications and best practices need to exist.
>      + Specifications feel like they're required in my opinion. I think some
>        cross-project things like service catalog we want under here.
>      + Best practices can be for rolling upgrades. While it's great if a project
>        can do rolling upgrades and use our existing solutions, according to some
>        experts there is no silver bullet to this problem.

This is not the first time in the life of the cross-project efforts that 
the difference between best practices and specs is biting us. I think 
those are different things, and so far we have stored them in the same 
repo, which kind of dilutes the messaging around them.

Best practices / guidelines are recommendations for future design. A set 
of documents to base your future work on. Best practices are living 
documents that are updated. They should not require full openstack-wide 
consensus, since they are just a recommendation. They might be removed 
when no longer relevant, but otherwise they don't expire and are never 

Specifications, I think, should be more about a specific implementation 
plan. A clear goal, a list of affected projects, steps to reach the goal 
and assignees to make it happen. Once approved by affected projects, 
they don't really change. Specs should have an end, at some point they 
should be considered implemented or abandoned.

Keeping both using the same template, in the same directories and the 
same repositories is what created this grey area that paved the way for 
specs without assignees and best practices asking for cross-project 
consensus that they will never fully obtain.

I think it's time to recognize those are different things and separate them.

Thierry Carrez (ttx)

More information about the OpenStack-dev mailing list