Governance/Approved/APIStability

Governance/Proposed/APIStability
Time:  <>

Drafter: markmc and david-kranz

Drafters Email:  <> and <>

Status:  Approved

API Stability Statement
It is critical to the success of OpenStack that operators be willing to upgrade to new OpenStack releases. All OpenStack APIs use a versioning scheme that is completely independent from the named releases (Essex, Folsom, etc.). One obstacle to upgrading to a new OpenStack release is if there are incompatible API changes that could cause user applications to stop working. Operators want great new features and APIs to be the only aspect of the upgrade process visible to their users. Old API versions should continue to work.

On the other hand, OpenStack is a maturing project and operators also want to see bugs fixed. Each of these bug fixes may introduce subtle behavioral changes that could potentially cause issues for existing clients which rely on the buggy behavior.

Each cloud operator may have their own idea of where the line should be drawn between legitimate bug fixes and and incompatible API changes. Some operators may be in the early stages of their deployment and value the bug fixes while not having a significant user base they are concerned about. Other operators may be highly risk averse and would prefer to see bug compatibility retained for ever rather than have a change impact a single user.

OpenStack should develop a clear view of where this line is drawn and all involved - developers, code reviewers, and QA engineers - should endeavour to apply a consistent set of guidelines when considering a change which may affect clients of an existing API version.

Those interested in helping to define these guidelines should contribute to the Evaluating API Changes document and discussions on the openstack-dev mailing list.