openstack team mailing list archive

[Mark McLoughlin <markmc@xxxxxxxxxx>]

Hey,

On Tue, 2012-01-03 at 16:57 +0000, Mark McLoughlin wrote:

> The openstack-common 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.

Jason and I have come up with a bit of a compromise on this front:

  http://wiki.openstack.org/CommonLibrary#Incubation

I've appended the text below. We've started with melange:

  http://review.openstack.org/3465

While we still think that we should be able to make API compat
guarantees about the openstack-common library, there needs to be a
stepping stone for new APIs which are shared between multiple projects
but aren't yet up to criteria required for inclusion in the library.

This is still evil copy-and-paste, but it's managed evilness :-)

Thanks,
Mark.

== Incubation ==

openstack-common 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 openstack-common 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 openstack-common
  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 .../openstack-common
  $> cd openstack-common
  $> 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 openstack-common
itself and copied into the project.

Developers making changes to incubating APIs in openstack-common 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 openstack-common library
proper.