Remove incubator policy
oslo-incubator has been retired so this is no longer relevant. Change-Id: Ib17305ff713da75c60a2891672ea961619b46415
This commit is contained in:
Ben Nemec
parent
17e24acb65
commit
cba6fecac6
@ -1,332 +0,0 @@
|
||||
..
|
||||
This content is based on the "Incubation" section of
|
||||
https://wiki.openstack.org/wiki/Oslo, which will be removed when the
|
||||
information is added to the specs repository history section.
|
||||
|
||||
====================
|
||||
The Oslo Incubator
|
||||
====================
|
||||
|
||||
Problem description
|
||||
===================
|
||||
|
||||
One source of code for Oslo libraries is code in an existing project
|
||||
that is identified as useful to another project. The existing
|
||||
implementation may be tightly coupled to the application, and need to
|
||||
be modified to make it more general. This spec describes how the
|
||||
"incubator" repository can be used to evolve the module's API to
|
||||
eventually make it suitable for release as a library.
|
||||
|
||||
Proposed Policy
|
||||
===============
|
||||
|
||||
The process of developing a new Oslo API usually begins by taking code
|
||||
which is common to some OpenStack projects and moving it into the
|
||||
`oslo-incubator`_ repository. New APIs live and evolve in the
|
||||
incubator until they have matured to meet the graduation criteria
|
||||
described below under "API Principles".
|
||||
|
||||
Using the incubator helps increase *developer* performance by making
|
||||
it possible to quickly change the API of a module, while postponing
|
||||
adoption of that API in the consuming application until it is
|
||||
convenient for the application review team.
|
||||
|
||||
Consider incubated code as "statically linked" to an application,
|
||||
while a graduated modules are "shared libraries".
|
||||
|
||||
.. _oslo-incubator: http://git.openstack.org/cgit/openstack/oslo-incubator
|
||||
|
||||
Syncing Code from Incubator
|
||||
---------------------------
|
||||
|
||||
APIs which are incubating can be copied into individual openstack
|
||||
projects from oslo-incubator using the ``update.py`` script provided
|
||||
(which may be invoked through the convenient ``update.sh``). An
|
||||
``openstack-common.conf`` configuration file in the project describes
|
||||
which modules to copy and where they should be copied to.
|
||||
|
||||
Usually the API maintainer or those making significant changes to an
|
||||
API take responsibility for syncing that specific module into the
|
||||
projects which use it by doing::
|
||||
|
||||
$> cd ../
|
||||
$> git clone git://git.openstack.org/openstack/oslo-incubator
|
||||
$> cd oslo-incubator
|
||||
$> ./update.sh --nodeps --base nova --dest-dir ../nova --modules jsonutils,gettextutils
|
||||
|
||||
Alternatively, it can make sense for someone to batch sync more minor
|
||||
changes into a project together. To sync all code for a specific
|
||||
project, you can do::
|
||||
|
||||
$> ./update.sh ../nova
|
||||
Copying the config,exception,extensions,utils,wsgi modules under the nova module in ../nova
|
||||
|
||||
In this latter case, the ``update.sh`` script uses the
|
||||
``openstack-common.conf`` config file to determine which modules to
|
||||
copy. The format of that file is::
|
||||
|
||||
$> 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
|
||||
|
||||
For master oslo-incubator sync requests, we tend to sync whole modules
|
||||
or even all the modules that a project uses (unless there are specific
|
||||
obstacles to doing so). This keeps the project up to date with the
|
||||
version of the modules tested together in the incubator.
|
||||
|
||||
.. note::
|
||||
|
||||
Developers making major changes to incubating APIs in
|
||||
``oslo-incubator`` must be prepared to work with :doc:`the Oslo
|
||||
liaisons <liaisons>` to update the copies in the projects which
|
||||
have previously imported the code.
|
||||
|
||||
The tests for incubated code should not be synced into consuming
|
||||
projects.
|
||||
|
||||
Stable Branches
|
||||
---------------
|
||||
|
||||
For stable branches, the process is a bit different. For those
|
||||
branches, we don't generally want to introduce changes that are not
|
||||
related to specific issues in a project. So in case of backports, we
|
||||
tend to do per-patch consideration when synchronizing from incubator.
|
||||
|
||||
Backporting for stable branches is a bit complicated process. When
|
||||
reviewing synchronization requests for those branches, we should not
|
||||
only check that the code is present in all consequent branches of the
|
||||
appropriate project (f.e. for N-2, in both N and N-1), but also that
|
||||
the patches being synchronized were successfully backported to
|
||||
corresponding stable branches of oslo-incubator. So the usual way of
|
||||
oslo-incubator bug fix is (in case of Neutron):
|
||||
|
||||
1. oslo-incubator (master)
|
||||
2. neutron (master)
|
||||
3. oslo-incubator (stable/icehouse)
|
||||
4. neutron (stable/icehouse).
|
||||
|
||||
For N-2, it's even more complicated, introducing more elements in the
|
||||
backporting chain.
|
||||
|
||||
Developer Impact
|
||||
----------------
|
||||
|
||||
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.
|
||||
|
||||
All changes related to code synchronization from ``oslo-incubator``,
|
||||
such as updating the use of APIs that have evolved, must be 'atomic'
|
||||
with the sync. For example, when syncing a new version of an incubator
|
||||
module that uses a library containing a newly graduated module, it may
|
||||
be necessary to update the rest of the application to use that same
|
||||
library, too. The Oslo team does not support versions of incubated
|
||||
modules with local changes, other than the import statements modified
|
||||
automatically by ``update.py``.
|
||||
|
||||
API Principles
|
||||
--------------
|
||||
|
||||
APIs included in Oslo should 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, we keep a number of principles in mind when designing and
|
||||
evolving Oslo APIs:
|
||||
|
||||
1. The API should be generally useful and a "good fit" - e.g. it
|
||||
shouldn't encode any 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 should already be in use by a number of OpenStack projects
|
||||
|
||||
3. There should be a commitment to adopt the API in all other
|
||||
OpenStack projects (where appropriate) and there should be no known
|
||||
major blockers to that adoption
|
||||
|
||||
4. The API should represents the "rough consensus" across OpenStack
|
||||
projects
|
||||
|
||||
5. There should be 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
|
||||
|
||||
Graduation
|
||||
----------
|
||||
|
||||
Code in the incubator is expected to move out to its own repository to
|
||||
be packaged as a standalone library or project. When that process
|
||||
starts, the ``MAINTAINERS`` file should be updated so the status of
|
||||
the module(s) is "Graduating". After this all changes should be
|
||||
proposed first to the new library repository, and then back-ported to
|
||||
the incubator if necessary. While the module is in the Graduating
|
||||
state, all bug fixes and features will need to be back-ported to the
|
||||
incubator and maintained in both repositories.
|
||||
|
||||
After the first release of the new library, the module(s) should be
|
||||
removed from the master branch of the incubator. During this phase,
|
||||
only critical bug fixes will be allowed to be back-ported to the prior
|
||||
stable branches. New features and minor bugs should be fixed in the
|
||||
released library only, and effort should be spent focusing on having
|
||||
downstream projects consume the library.
|
||||
|
||||
Testing Impact
|
||||
--------------
|
||||
|
||||
Tests for incubated code should be managed in the test suite in the
|
||||
``oslo-incubator`` repository. Tests should be organized in a way to
|
||||
make them easy to graduate along with the production code when the
|
||||
library is graduating.
|
||||
|
||||
The tests for incubated code should not be synced into consuming
|
||||
projects.
|
||||
|
||||
Specialist Maintainers
|
||||
----------------------
|
||||
|
||||
While incubating, all APIs should have at least one specialist API
|
||||
maintainer. The responsibility of these maintainers and the list of
|
||||
maintainers for each incubating API is documented in the
|
||||
``MAINTAINERS`` file in ``oslo-incubator``.
|
||||
|
||||
The maintainer's +1 vote on code related to their specialty is
|
||||
considered as a +2 for approval purposes.
|
||||
|
||||
Adoption
|
||||
--------
|
||||
|
||||
We assume the application from which the incubated code is copied will
|
||||
use the incubated version as part of the evolution process. One other
|
||||
application should be identified for integration as well, to provide
|
||||
more input into whether the API is sufficiently generalized. The
|
||||
number of applications using the incubated module should be minimized
|
||||
until the library graduates.
|
||||
|
||||
Because the graduated module is removed from the master branch of the
|
||||
incubator when the library is created, consuming applications should
|
||||
move to adopt the library as quickly as possible. We expect adoption
|
||||
to be complete by the end of the first full cycle after the new
|
||||
library is created.
|
||||
|
||||
Library
|
||||
-------
|
||||
|
||||
Each new incubated module should have a full life-cycle plan worked
|
||||
out before incubation begins. See the default spec template in
|
||||
``oslo-specs`` for details.
|
||||
|
||||
Anticipated API Stabilization
|
||||
-----------------------------
|
||||
|
||||
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.
|
||||
|
||||
Alternatives
|
||||
============
|
||||
|
||||
Direct-to-Library
|
||||
-----------------
|
||||
|
||||
Not all Oslo modules need to be incubated. Ideas for new libraries or
|
||||
library components may lead to creating a library "from scratch". This
|
||||
approach is suitable when the purpose of the module is understood up
|
||||
front, and there is no existing code coupled to the rest of an
|
||||
application's code base.
|
||||
|
||||
Examples of Oslo libraries that used this approach successfully
|
||||
include cliff, stevedore, and taskflow.
|
||||
|
||||
Adoption
|
||||
--------
|
||||
|
||||
Existing libraries, possibly created outside of the OpenStack project,
|
||||
can be "adopted" by the Oslo team, who then takes over maintenance
|
||||
duties.
|
||||
|
||||
Examples of adopted Oslo libraries include tooz and PyCADF.
|
||||
|
||||
Incubating in Place
|
||||
-------------------
|
||||
|
||||
Not all application modules are tightly coupled to the other parts of
|
||||
the application in which they live. In these cases, it may be faster
|
||||
to evolve the API in place in the application's repository, and
|
||||
graduate directly from there to a new library.
|
||||
|
||||
oslo.versionedobjects is an example of an Oslo library that incubated
|
||||
in place (in the nova source repository).
|
||||
|
||||
References
|
||||
==========
|
||||
|
||||
* File bugs for incubating APIs in the `oslo-incubator project`_ in
|
||||
launchpad.
|
||||
|
||||
* Instructions for the graduation process evolve over time, so we keep
|
||||
them in the wiki. See `Oslo/CreatingANewLibrary`_
|
||||
|
||||
* We track the graduation status of incubated code in the wiki in
|
||||
`Oslo/GraduationStatus`_.
|
||||
|
||||
* Mailing list discussions of handling feature requests for code being
|
||||
graduated:
|
||||
|
||||
* http://lists.openstack.org/pipermail/openstack-dev/2013-November/020742.html
|
||||
* http://lists.openstack.org/pipermail/openstack-dev/2013-December/020771.html
|
||||
|
||||
* Mailing list discussion of deprecation process for graduating code:
|
||||
http://lists.openstack.org/pipermail/openstack-dev/2014-March/029936.html
|
||||
|
||||
* Mailing list discussion of the change to deleting code instead of
|
||||
marking it obsolete:
|
||||
http://lists.openstack.org/pipermail/openstack-dev/2014-August/044360.html
|
||||
|
||||
* `Taking the Long View
|
||||
<http://www.slideshare.net/doughellmann/taking-the-long-view-how-the-oslo-program-reduces-technical-debt>`_,
|
||||
Kilo summit presentation by Doug Hellmann and Mark McLoughlin with
|
||||
some history of the incubator.
|
||||
|
||||
.. _Oslo/CreatingANewLibrary: https://wiki.openstack.org/wiki/Oslo/CreatingANewLibrary
|
||||
|
||||
.. _oslo-incubator project: https://launchpad.net/oslo-incubator
|
||||
|
||||
.. _Oslo/GraduationStatus: https://wiki.openstack.org/wiki/Oslo/GraduationStatus
|
||||
|
||||
Revision History
|
||||
================
|
||||
|
||||
.. list-table:: Revisions
|
||||
:header-rows: 1
|
||||
|
||||
* - Release Name
|
||||
- Description
|
||||
* - Essex
|
||||
- Incubator created as ``openstack-common`` repository
|
||||
* - Folsom
|
||||
- "Managed copy and paste" concepts developed
|
||||
* - Juno
|
||||
- Decide to delete graduating modules from the incubator after
|
||||
one full cycle.
|
||||
* - Kilo
|
||||
- Change policy to delete graduating modules immediately after
|
||||
the library is released.
|
||||
|
||||
.. note::
|
||||
|
||||
This work is licensed under a Creative Commons Attribution 3.0
|
||||
Unported License.
|
||||
http://creativecommons.org/licenses/by/3.0/legalcode
|
||||
Loading…
Reference in New Issue
Block a user