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 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.
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 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
- The API represents the "rough consensus" across OpenStack projects
- There is no other API in OpenStack competing for this "rough consensus"
- 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
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.
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 .../melange $> cd melange $> 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=melange
and then, to copy the code across:
$> cd ../ $> git clone .../oslo-incubator $> cd oslo-incubator $> python update.py ../melange Copying the config,exception,extensions,utils,wsgi modules under the melange module in ../melange
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 the oslo-incubator library proper.