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.
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:
- 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
- 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
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=cfg,iniparser # 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
As an alternative to using the config file, you can do:
$> python update.py --base nova --dest-dir ../nova --modules cfg,iniparser
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.