Jump to: navigation, search

Difference between revisions of "Oslo"

Line 2: Line 2:
 
= Oslo =
 
= Oslo =
  
The oslo-incubator project intends to produce a python library containing infrastructure code shared by [[OpenStack]] projects. The APIs provided by the project should be high quality, stable, consistent and generally useful.
+
The Oslo project produces a set of python libraries containing infrastructure code shared by [[OpenStack]] projects. The APIs provided by these libraries should be high quality, stable, consistent and generally useful.
  
The existence of an API in the oslo-incubator library should be indicitative of rough consensus across the project on that API's design. New [[OpenStack]] projects should be able to use an API in the library safe in the knowledge that, by doing so, the project is being a good [[OpenStack]] citizen and building upon established best practice.
+
== Incubation ==
 +
 
 +
APIs included in Oslo should be reflect a rough consensus across the project on the requirements and design for that use case. New [[OpenStack]] projects should be able to use an Oslo API safe in the knowledge that, by doing so, the project is being a good [[OpenStack]] citizen and building upon established best practice.
  
 
To that end, a number of principles should be adhered to when considering any proposed API for oslo-incubator:
 
To that end, a number of principles should be adhered to when considering any proposed API for oslo-incubator:
  
# The API is generally useful and is a "good fit" - e.g. it doesn't encode some assumptions specific to the project it originated from, it should follow a style consistent with other oslo-incubator APIs and should fit generally in a theme like error handling, configuration options, time and date, notifications, WSGI, etc.
+
# The API is generally useful and is a "good fit" - e.g. it doesn't encode some assumptions specific to the project it originated from, it should follow a style consistent with other Oslo APIs and should fit generally in a theme like error handling, configuration options, time and date, notifications, WSGI, etc.
 
# The API is already in use by a number of [[OpenStack]] projects
 
# The API is already in use by a number of [[OpenStack]] projects
 
# There is a commitment to adopt the API in all other [[OpenStack]] projects (where appropriate) and there are no known major blockers to that adoption
 
# There is a commitment to adopt the API in all other [[OpenStack]] projects (where appropriate) and there are no known major blockers to that adoption
Line 17: Line 19:
 
== Incubation ==
 
== Incubation ==
  
oslo-incubator also provides a process for incubating APIs which, while they are shared between multiple [[OpenStack]] projects, have not yet matured to meet the criteria described above.
+
The process of developing a new Oslo API begins by taking code which is common to some [[OpenStack]] projects and moving it into the [https://github.com/openstack/oslo-incubator oslo-incubator] repository. New APIs live in the incubator until they have matured to meet the criteria described above.
  
 
APIs which are incubating can be copied into individual openstack projects from oslo-incubator using the <code><nowiki>update.py</nowiki></code> script provided. An <code><nowiki>openstack-common.conf</nowiki></code> configuration file in the project describes which modules to copy and where they should be copied to e.g.
 
APIs which are incubating can be copied into individual openstack projects from oslo-incubator using the <code><nowiki>update.py</nowiki></code> script provided. An <code><nowiki>openstack-common.conf</nowiki></code> configuration file in the project describes which modules to copy and where they should be copied to e.g.
Line 23: Line 25:
  
 
<pre><nowiki>
 
<pre><nowiki>
$> git clone .../melange
+
$> git clone .../nova
$> cd melange
+
$> cd nova
 
$> cat openstack-common.conf
 
$> cat openstack-common.conf
 
[DEFAULT]
 
[DEFAULT]
Line 32: Line 34:
  
 
# The base module to hold the copy of openstack.common
 
# The base module to hold the copy of openstack.common
base=melange
+
base=nova
 
</nowiki></pre>
 
</nowiki></pre>
  
Line 43: Line 45:
 
$> git clone .../oslo-incubator
 
$> git clone .../oslo-incubator
 
$> cd oslo-incubator
 
$> cd oslo-incubator
$> python update.py ../melange
+
$> python update.py ../nova
Copying the config,exception,extensions,utils,wsgi modules under the melange module in ../melange
+
Copying the config,exception,extensions,utils,wsgi modules under the nova module in ../nova
 
</nowiki></pre>
 
</nowiki></pre>
  
Line 52: Line 54:
 
Developers making changes to incubating APIs in oslo-incubator must be prepared to update the copies in the projects which have previously imported the code.
 
Developers making changes to incubating APIs in oslo-incubator must be prepared to update the copies in the projects which have previously imported the code.
  
Incubation shouldn't be seen as a long term option for any API - it is merely a stepping stone to inclusion into the oslo-incubator library proper.
+
Incubation shouldn't be seen as a long term option for any API - it is merely a stepping stone to inclusion into a published Oslo library.

Revision as of 17:20, 22 November 2012

Oslo

The Oslo project produces a set of python libraries containing infrastructure code shared by OpenStack projects. The APIs provided by these libraries should be high quality, stable, consistent and generally useful.

Incubation

APIs included in Oslo should be reflect a rough consensus across the project on the requirements and design for that use case. New OpenStack projects should be able to use an Oslo API safe in the knowledge that, by doing so, the project is being a good OpenStack citizen and building upon established best practice.

To that end, a number of principles should be adhered to when considering any proposed API for oslo-incubator:

  1. The API is generally useful and is a "good fit" - e.g. it doesn't encode some assumptions specific to the project it originated from, it should follow a style consistent with other Oslo APIs and should fit generally in a theme like error handling, configuration options, time and date, notifications, WSGI, etc.
  2. The API is already in use by a number of OpenStack projects
  3. There is a commitment to adopt the API in all other OpenStack projects (where appropriate) and there are no known major blockers to that adoption
  4. The API represents the "rough consensus" across OpenStack projects
  5. There is no other API in OpenStack competing for this "rough consensus"
  6. It should be possible for the API to evolve while continuing to maintain backwards compatibility with older versions for a reasonable period - e.g. compatibility with an API deprecated in release N may only be removed in release N+2

Incubation

The process of developing a new Oslo API begins by taking code which is common to some OpenStack projects and moving it into the oslo-incubator repository. New APIs live in the incubator until they have matured to meet the criteria described above.

APIs which are incubating can be copied into individual openstack projects from oslo-incubator using the update.py script provided. An openstack-common.conf configuration file in the project describes which modules to copy and where they should be copied to e.g.


$> git clone .../nova
$> cd nova
$> cat openstack-common.conf
[DEFAULT]

# The list of modules to copy from oslo-incubator
modules=config,exception,extensions,utils,wsgi

# The base module to hold the copy of openstack.common
base=nova


and then, to copy the code across:


$> cd ../
$> git clone .../oslo-incubator
$> cd oslo-incubator
$> python update.py ../nova
Copying the config,exception,extensions,utils,wsgi modules under the nova module in ../nova


Projects which are using such incubating APIs must avoid ever modifying their copies of the code. All changes should be made in oslo-incubator itself and copied into the project.

Developers making changes to incubating APIs in oslo-incubator must be prepared to update the copies in the projects which have previously imported the code.

Incubation shouldn't be seen as a long term option for any API - it is merely a stepping stone to inclusion into a published Oslo library.